[PATCH v7 0/7] Enable doing a shallow clone of a specific git revision

The goal of this series is to add an option `--revision` to git-clone(1).

This series starts with a handful of preparatory refactoring commits that make it more straight-forward to add this new option. In the last commit we're actually adding the feature.

This series sets an example on how I think we can further refactor builtin/clone.c to increase the maintainability of the code.

---
Changes in v7:
- Further enhance documentation of option --revision on git-clone(1).
- Indentation fix in builtin/clone.c.
- Link to v6: https://lore.kernel.org/r/20250205-toon-clone-refs-v6-0-0bbc8e6d89fd@iotcl.com

Changes in v6:
- Rewrite the documentation for git-clone(1) --[no-]tags.
- Remove unneeded conditional around die_for_incompatible_opt2() in
  builtin/replay.c.
- Fix typo in code comment in builtin/clone.c.
- Link to v5: https://lore.kernel.org/r/20250204-toon-clone-refs-v5-0-37e34af283c8@iotcl.com

Changes in v5:
- Add separate commit to introduce die_for_incompatible_opt2()
- Small tweaks in documentation about `--[no-]tags` and `--revision`.
- Better explain the refactoring of wanted_peer_refs() in the commit
  message.
- Change type from `int` to `size_t` in wanted_peer_refs().
- Use lookup_commit_or_die() instead lookup_commit_reference() to avoid
  checking the result ourself.
- Add a few code comments to explain some things.
- Stylish cleanups like removal of unneeded empty lines, commented out
  test-code and remarks.
- Link to v4: https://lore.kernel.org/r/20250131-toon-clone-refs-v4-0-2a4ff851498f@iotcl.com

Changes in v4:
- Introduce a new commit to reduce the use of global variables.
- Introduce a new commit to invert the flag --no-tags to --tags.
- Introduce a new commit to refactor wanted_peer_refs() in
  builtin/clone.c.
- Introduce a new commit to shuffle the handling of tags refspec.
- Introduce a new commit to introduce a `struct clone_opts`.
- Link to v3: https://lore.kernel.org/r/20241219-toon-clone-refs-v3-1-1484faea3008@iotcl.com

Changes in v3:
- Fail early when the revision was not found on the remote, instead of
  creating a clone that's in an invalid state.
- State more clearly in the commit message adding this option is useful
  for a not uncommon use-case.
- Be explicit in the documentation the ref needs to peel down to a
  commit.
- Die in case we try to update_head() to an object that's not a commit.
- Allow combining `--revision` with `--bare`.
- Add die_for_incompatible_opt2() to parse-options.h and use it for the
  options that are not compatible with the new `--revision` option.
- Small tweaks to the added tests.
- Small touchups on commit messages.
- Link to v2: https://lore.kernel.org/r/20241129-toon-clone-refs-v2-1-dca4c19a3510@iotcl.com

---
Toon Claes (7):
      clone: cut down on global variables in clone.c
      clone: make it possible to specify --tags
      clone: refactor wanted_peer_refs()
      clone: add tags refspec earlier to fetch refspec
      clone: introduce struct clone_opts in builtin/clone.c
      parse-options: introduce die_for_incompatible_opt2()
      builtin/clone: teach git-clone(1) the --revision= option

 Documentation/git-clone.txt |  26 +++-
 builtin/clone.c             | 350 +++++++++++++++++++++++++-------------------
 builtin/replay.c            |   7 +-
 parse-options.h             |   9 ++
 remote.c                    |   2 +-
 remote.h                    |   5 +
 t/meson.build               |   1 +
 t/t5621-clone-revision.sh   | 123 ++++++++++++++++
 8 files changed, 358 insertions(+), 165 deletions(-)
---

Range-diff versus v6:

1:  14e4210ef9 = 1:  e9d0d1bb4e clone: cut down on global variables in clone.c
2:  f85beed07e = 2:  5c570e08f6 clone: make it possible to specify --tags
3:  92b998a173 = 3:  bb5d206ee6 clone: refactor wanted_peer_refs()
4:  3fb2766728 = 4:  344a2f143c clone: add tags refspec earlier to fetch refspec
5:  d0341cad24 = 5:  93d074d17e clone: introduce struct clone_opts in builtin/clone.c
6:  d42f291e48 = 6:  457f21943e parse-options: introduce die_for_incompatible_opt2()
7:  3f332971dc ! 7:  fb4f05547e builtin/clone: teach git-clone(1) the --revision= option
    @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
     +`--revision=<rev>`::
     +	Create a new repository, and fetch the history leading to the given
     +	revision _<rev>_ (and nothing else), without making any remote-tracking
    -+	branch, and without making any local branch, and point `HEAD` to
    -+	_<rev>_. When creating a non-bare repository, the revision is checked
    -+	out on a detached `HEAD`. The argument can be a ref name
    -+	(e.g. `refs/heads/main` or `refs/tags/v1.0`) that peels down to a
    -+	commit, or a hexadecimal object name.
    ++	branch, and without making any local branch, and detach `HEAD` to
    ++	_<rev>_. The argument can be a ref name (e.g. `refs/heads/main` or
    ++	`refs/tags/v1.0`) that peels down to a commit, or a hexadecimal object
    ++	name.
     +	This option is incompatible with `--branch` and `--mirror`.
     +
      `-u` _<upload-pack>_::
    @@ builtin/clone.c: static void update_head(const struct ref *our, const struct ref
     -		struct commit *c = lookup_commit_reference(the_repository,
     -							   &our->old_oid);
     +		struct commit *c = lookup_commit_or_die(&our->old_oid,
    -+						        our->name);
    ++							our->name);
     +
      		/* --branch specifies a non-branch (i.e. tags), detach HEAD */
      		refs_update_ref(get_main_ref_store(the_repository), msg,

---

base-commit: bc204b742735ae06f65bb20291c95985c9633b7f change-id: 20241129-toon-clone-refs-ad3623772f92

Thanks -- Toon