Re: [PATCH 1/5] revisions.txt: document more special refs

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 14, 2023, 18:49 UTC
Message-ID: <xmqq8reuqoyk.fsf@gitster.g>
In-Reply-To: <66c7e514157f3c8220eb994cea7c4659d5241042.1681495119.git.gitgitgadget@gmail.com>

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 25 quoted lines

> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> Some special refs, namely HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and
> CHERRY_PICK_HEAD, are mentioned and described in 'gitrevisions', but some
> others, namely REBASE_HEAD, REVERT_HEAD, and BISECT_HEAD, are not.
>
> Add a small description of these special refs.
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
>  Documentation/revisions.txt | 11 +++++++++--
>  1 file changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 9aa58052bc7..98b8f89bc8d 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -32,8 +32,8 @@ characters and to avoid word splitting.
>    first match in the following rules:
>  
>    . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
> -    useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`
> -    and `CHERRY_PICK_HEAD`);
> +    useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`,
> +    `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`);

Adding missing ones and enumerating them indeed is good, but I wonder if the readers will be helped if they are exposed to the phrase "pseudoref" here.

	This is usually useful only for the pseudorefs, i.e. `HEAD`,
	`FETCH_HEAD`, ..."

We have definition of it in the glossary, but it does not have an exhaustive list (and if we want to have an exhausitive list on this page, the glossary definition of pseudoref may want to point at this page).

It is an unrelated tangent that shouldn't be added to the documentation (yet), but didn't we have a plan to limit the pseudorefs to those names that end with "_HEAD"?

> +`REBASE_HEAD`, during a rebase, records the commit at which the
> +operation is currently stopped, either because of conflicts or an `edit`
> +command in an interactive rebase.

OK.

> +`REVERT_HEAD` records the commit which you are reverting when you
> +run `git revert`.

OK.

> +`BISECT_HEAD` records the current commit to be tested when you
> +run `git bisect --no-checkout`.

OK.

Looking very good.