From: Junio C Hamano <gitster@pobox.com>
To: "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Elijah Newren <newren@gmail.com>,
Johannes Schindelin <Johannes.Schindelin@gmx.de>,
Philippe Blain <levraiphilippeblain@gmail.com>
Subject: Re: [PATCH 1/5] revisions.txt: document more special refs
Date: Fri, 14 Apr 2023 11:49:07 -0700 [thread overview]
Message-ID: <xmqq8reuqoyk.fsf@gitster.g> (raw)
In-Reply-To: <66c7e514157f3c8220eb994cea7c4659d5241042.1681495119.git.gitgitgadget@gmail.com> (Philippe Blain via GitGitGadget's message of "Fri, 14 Apr 2023 17:58:34 +0000")
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 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.
next prev parent reply other threads:[~2023-04-14 18:49 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
2023-04-14 17:58 ` [PATCH 1/5] revisions.txt: document " Philippe Blain via GitGitGadget
2023-04-14 18:49 ` Junio C Hamano [this message]
2023-04-15 5:18 ` Felipe Contreras
2023-04-14 19:49 ` Victoria Dye
2023-04-14 21:14 ` Taylor Blau
2023-04-15 5:35 ` Felipe Contreras
2023-04-14 17:58 ` [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
2023-04-14 20:25 ` Junio C Hamano
2023-04-14 17:58 ` [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
2023-04-14 20:36 ` Junio C Hamano
2023-04-14 17:58 ` [PATCH 4/5] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
2023-04-14 21:41 ` Taylor Blau
2023-04-15 5:08 ` Eric Sunshine
2023-04-15 7:08 ` Elijah Newren
2023-04-15 8:55 ` Eric Sunshine
2023-04-16 3:05 ` Elijah Newren
2023-04-15 7:03 ` Elijah Newren
2023-04-15 15:36 ` Philippe Blain
2023-04-15 23:31 ` Elijah Newren
2023-04-14 17:58 ` [PATCH 5/5] completion: complete AUTO_MERGE Philippe Blain via GitGitGadget
2023-04-14 18:34 ` [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Junio C Hamano
2023-04-14 19:49 ` Victoria Dye
2023-04-15 7:09 ` Elijah Newren
2023-04-16 10:26 ` Chris Torek
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 1/6] revisions.txt: use description list for " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 2/6] revisions.txt: document more " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 3/6] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 4/6] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
2023-05-22 19:29 ` [PATCH v2 5/6] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
2023-05-22 19:29 ` [PATCH v2 6/6] completion: complete AUTO_MERGE Philippe Blain via GitGitGadget
2023-06-01 6:18 ` [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs Elijah Newren
2023-06-01 7:32 ` Junio C Hamano
2023-06-01 7:30 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq8reuqoyk.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=Johannes.Schindelin@gmx.de \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=levraiphilippeblain@gmail.com \
--cc=newren@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).