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

From: Victoria Dye <[email-masked]>
Date: Fri, 14 Apr 2023 12:49:16 -0700

Philippe Blain via GitGitGadget wrote:
> @@ -55,8 +55,15 @@ you can easily change the tip of the branch back to the state before you ran
>  them.
>  `MERGE_HEAD` records the commit(s) which you are merging into your branch
>  when you run `git merge`.
> +`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.
> +`REVERT_HEAD` records the commit which you are reverting when you
> +run `git revert`.
>  `CHERRY_PICK_HEAD` records the commit which you are cherry-picking
>  when you run `git cherry-pick`.
> +`BISECT_HEAD` records the current commit to be tested when you
> +run `git bisect --no-checkout`.

This is a fairly minor point, so feel free to ignore if you disagree or feel
it's not worth the effort:

Although the special refs in this list (HEAD, MERGE_HEAD, REBASE_HEAD etc.)
are visually separated by newlines in this doc, they render in the manpages
& HTML in a single monolithic paragraph (see [1]). With the addition of
three more descriptions (four if you count 'AUTO_MERGE' in patch 4/5), that
paragraph is getting large enough that it might be difficult for a reader to
parse and find information about a specific ref. 

To help with that, you could create visual separation in the rendered doc by
adding a '+' between each special ref description; converting them into a
bullet pointed list would also work, I think.

[1] https://git-scm.com/docs/revisions#Documentation/revisions.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem

>  +
>  Note that any of the 'refs/*' cases above may come either from
>  the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.