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

From: Victoria Dye <vdye@github.com>
Date: Apr 14, 2023, 19:49 UTC
Message-ID: <ebcf2426-db40-e967-9db5-532869cac8ff@github.com>
In-Reply-To: <66c7e514157f3c8220eb994cea7c4659d5241042.1681495119.git.gitgitgadget@gmail.com>

Philippe Blain via GitGitGadget wrote:

Show 13 quoted lines

> @@ -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.