Re: [PATCH v4 6/6] builtin/clone: teach git-clone(1) the --revision= option

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Friday, 31 January 2025 16:30:34 UTC+1 Toon Claes wrote:
> The git-clone(1) command has the option `--branch` that allows the user
> to select the branch they want HEAD to point to. In a non-bare
> repository this also checks out that branch.
> 
> Option `--branch` also accepts a tag. When a tag name is provided, the
> commit this tag points to is checked out and HEAD is detached. Thus
> `--branch` can be used to clone a repository and check out a ref kept
> under `refs/heads` or `refs/tags`. But some other refs might be in use
> as well. For example Git forges might use refs like `refs/pull/<id>` and
> `refs/merge-requests/<id>` to track pull/merge requests. These refs
> cannot be selected upon git-clone(1).
> 
> Add option `--revision` to git-clone(1). This option accepts a fully
> qualified reference, or a hexadecimal commit ID. This enables the user
> to clone and check out any revision they want. `--revision` can be used
> in conjunction with `--depth` to do a minimal clone that only contains
> the blob and tree for a single revision. This can be useful for
> automated tests running in CI systems.
> 
> Using option `--branch` and `--single-branch` together is a similar
> scenario, but serves a different purpose. Using these two options, a
> singlet remote tracking branch is created and the fetch refspec is set
> up so git-fetch(1) will receive updates on that branch from the remote.
> This allows the user work on that single branch.
> 
> Option `--revision` on contrary detaches HEAD, creates no tracking
> branches, and writes no fetch refspec.
> 
> Signed-off-by: Toon Claes <toon@iotcl.com>
> ---
>  Documentation/git-clone.txt |  10 ++++
>  builtin/clone.c             |  59 +++++++++++++++++----
>  parse-options.h             |   9 ++++
>  t/meson.build               |   1 +
>  t/t5621-clone-revision.sh   | 123
> ++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 193
> insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index
> 
99a9222e63429b3447deb3e7c08962d4ec60a295..6c882b6fc56c2595059124cd0ecdaf825e3
> 10160 100644 --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -221,6 +221,16 @@ objects from the source repository into a pack in the
> cloned repository. `--branch` can also take tags and detaches the `HEAD` at
> that commit in the resulting repository.
> 
> +`--revision` _<rev>_::

You can use the backticks for full synopsis style: `--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.
> +	This option is incompatible with `--branch` and `--mirror`.
> +
>  `-u` _<upload-pack>_::
>  `--upload-pack` _<upload-pack>_::
>  	When given, and the repository to clone from is accessed
> diff --git a/builtin/clone.c b/builtin/clone.c
> index