[PATCH 0/5] make room for "special ref"

[PATCH 0/5] make room for "special ref"

[Junio C Hamano]

Patrick's reftable work is progressing nicely and wants to establish
"special ref" as a phrase with some defined meaning that is somewhat
different from a mere "pseudo ref".

A pseudo ref is merely a normal ref with a funny naming convention,
i.e., being outside the refs/ hierarchy and has names with all
uppercase letters (or an underscore).  But there truly are refs that
are more than that.  For example, FETCH_HEAD currently stores not
just a single object name, but can and is used to store multiple
object names, each with annotations to record where they came from.
There indeed may be a need to introduce a new term to refer to such
"special refs".

Existing documentation, however, uses "special ref" to refer to
pseudo refs without any "special" property, like FETCH_HEAD does.

This series merely corrects such existing uses of the word, to make
room for Patrick's series to introduce (and formally define in the
glossary) "special refs".

Junio C Hamano (5):
  git.txt: HEAD is not that special
  git-bisect.txt: BISECT_HEAD is not that special
  refs.h: HEAD is not that special
  docs: AUTO_MERGE is not that special
  docs: MERGE_AUTOSTASH is not that special

 Documentation/git-bisect.txt    | 2 +-
 Documentation/git-diff.txt      | 2 +-
 Documentation/git-merge.txt     | 2 +-
 Documentation/git.txt           | 7 ++++---
 Documentation/merge-options.txt | 2 +-
 Documentation/user-manual.txt   | 2 +-
 refs.h                          | 2 +-
 7 files changed, 10 insertions(+), 9 deletions(-)

-- 
2.43.0-76-g1a87c842ec

[PATCH 1/5] git.txt: HEAD is not that special

[Junio C Hamano]

The introductory text in "git help git" that describes HEAD called
it "a special ref".  It is special compared to the more regular refs
like refs/heads/master and refs/tags/v1.0.0, but not that special,
unlike truly special ones like FETCH_HEAD.

Rewrite a few sentences to also introduce the distinction between a
regular ref that contain the object name and a symbolic ref that
contain the name of another ref.  Update the description of HEAD
that point at the current branch to use the more correct term, a
"symbolic ref".

This was found as part of auditing the documentation and in-code
comments for uses of "special ref" that refer merely a "pseudo ref".

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 2535a30194..880cdc5d7f 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for
 efficiency may later be compressed together into "pack files".
 
 Named pointers called refs mark interesting points in history.  A ref
-may contain the SHA-1 name of an object or the name of another ref.  Refs
-with names beginning `ref/head/` contain the SHA-1 name of the most
+may contain the SHA-1 name of an object or the name of another ref (the
+latter is called a "symbolic ref").
+Refs with names beginning `ref/head/` contain the SHA-1 name of the most
 recent commit (or "head") of a branch under development.  SHA-1 names of
-tags of interest are stored under `ref/tags/`.  A special ref named
+tags of interest are stored under `ref/tags/`.  A symbolic ref named
 `HEAD` contains the name of the currently checked-out branch.
 
 The index file is initialized with a list of all paths and, for each
-- 
2.43.0-76-g1a87c842ec

Re: [PATCH 1/5] git.txt: HEAD is not that special

[Ramsay Jones]

On 15/12/2023 20:32, Junio C Hamano wrote:
> The introductory text in "git help git" that describes HEAD called
> it "a special ref".  It is special compared to the more regular refs
> like refs/heads/master and refs/tags/v1.0.0, but not that special,
> unlike truly special ones like FETCH_HEAD.
> 
> Rewrite a few sentences to also introduce the distinction between a
> regular ref that contain the object name and a symbolic ref that
> contain the name of another ref.  Update the description of HEAD
> that point at the current branch to use the more correct term, a
> "symbolic ref".
> 
> This was found as part of auditing the documentation and in-code
> comments for uses of "special ref" that refer merely a "pseudo ref".
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/git.txt | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 2535a30194..880cdc5d7f 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for
>  efficiency may later be compressed together into "pack files".
>  
>  Named pointers called refs mark interesting points in history.  A ref
> -may contain the SHA-1 name of an object or the name of another ref.  Refs
> -with names beginning `ref/head/` contain the SHA-1 name of the most
> +may contain the SHA-1 name of an object or the name of another ref (the
> +latter is called a "symbolic ref").
> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most

Hmm, s:ref/head:refs/heads: right?

>  recent commit (or "head") of a branch under development.  SHA-1 names of
> -tags of interest are stored under `ref/tags/`.  A special ref named
> +tags of interest are stored under `ref/tags/`.  A symbolic ref named
>  `HEAD` contains the name of the currently checked-out branch.
>  
>  The index file is initialized with a list of all paths and, for each

Re: [PATCH 1/5] git.txt: HEAD is not that special

[Junio C Hamano]

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

>> -may contain the SHA-1 name of an object or the name of another ref.  Refs
>> -with names beginning `ref/head/` contain the SHA-1 name of the most
>> +may contain the SHA-1 name of an object or the name of another ref (the
>> +latter is called a "symbolic ref").
>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>
> Hmm, s:ref/head:refs/heads: right?

Yeah, right, not a new problem with this change, but is indeed a
good thing to catch and correct.  Thanks for a careful review.

Re: [PATCH 1/5] git.txt: HEAD is not that special

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
>
>>> -may contain the SHA-1 name of an object or the name of another ref.  Refs
>>> -with names beginning `ref/head/` contain the SHA-1 name of the most
>>> +may contain the SHA-1 name of an object or the name of another ref (the
>>> +latter is called a "symbolic ref").
>>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>>
>> Hmm, s:ref/head:refs/heads: right?
>
> Yeah, right, not a new problem with this change, but is indeed a
> good thing to catch and correct.  Thanks for a careful review.

And we have ref/tags/ just below, which I also have fixed locally.

[PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy

[Junio C Hamano]

There is no 'ref/notes/' hierarchy.  '[format] notes = foo' uses notes
that are found in 'refs/notes/foo'.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 * According to my eyeballing "git grep refs/ Documentation" result,
   this was the only remaining mention of "ref/" in Documentation/
   hierarchy that misspells "refs/".

 Documentation/config/format.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git c/Documentation/config/format.txt w/Documentation/config/format.txt
index c98412b697..7410e930e5 100644
--- c/Documentation/config/format.txt
+++ w/Documentation/config/format.txt
@@ -119,7 +119,7 @@ format.notes::
 	`--notes=<ref>`, where `ref` is the non-boolean value. Defaults
 	to false.
 +
-If one wishes to use the ref `ref/notes/true`, please use that literal
+If one wishes to use the ref `refs/notes/true`, please use that literal
 instead.
 +
 This configuration can be specified multiple times in order to allow

Re: [PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 4554 bytes --]

On Fri, Dec 15, 2023 at 02:28:00PM -0800, Junio C Hamano wrote:
> There is no 'ref/notes/' hierarchy.  '[format] notes = foo' uses notes
> that are found in 'refs/notes/foo'.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  * According to my eyeballing "git grep refs/ Documentation" result,
>    this was the only remaining mention of "ref/" in Documentation/
>    hierarchy that misspells "refs/".

This made me look for additional instances where we were referring to
"ref/". Turns out it's only a very limited set, see the below diff. Take
the translation changes with a big grain of salt though, and neither am
I sure whether we want to fix up past release notes. Also, the test is
interesting because it would fail even if we didn't pass an invalid atom
to git-for-each-ref(1).

Anyway, the patch you have looks obviously correct to me. I would be
happy to turn the below diff into a proper patch, but also wouldn't mind
to let you roll them into your patch series. Please let me know your
preference.

Patrick

diff --git a/Documentation/RelNotes/2.1.1.txt b/Documentation/RelNotes/2.1.1.txt
index 830fc3cc6d..d46e142119 100644
--- a/Documentation/RelNotes/2.1.1.txt
+++ b/Documentation/RelNotes/2.1.1.txt
@@ -29,7 +29,7 @@ Git v2.1.1 Release Notes
  * "git add x" where x that used to be a directory has become a
    symbolic link to a directory misbehaved.
 
- * The prompt script checked $GIT_DIR/ref/stash file to see if there
+ * The prompt script checked $GIT_DIR/refs/stash file to see if there
    is a stash, which was a no-no.
 
  * "git checkout -m" did not switch to another branch while carrying
diff --git a/Documentation/RelNotes/2.2.0.txt b/Documentation/RelNotes/2.2.0.txt
index e98ecbcff6..806908ddb2 100644
--- a/Documentation/RelNotes/2.2.0.txt
+++ b/Documentation/RelNotes/2.2.0.txt
@@ -205,7 +205,7 @@ notes for details).
  * "git add x" where x used to be a directory and is now a
    symbolic link to a directory misbehaved.
 
- * The prompt script checked the $GIT_DIR/ref/stash file to see if there
+ * The prompt script checked the $GIT_DIR/refs/stash file to see if there
    is a stash, which was a no-no.
 
  * Pack-protocol documentation had a minor typo.
diff --git a/po/fr.po b/po/fr.po
index ee2e610ef1..744550b056 100644
--- a/po/fr.po
+++ b/po/fr.po
@@ -19773,7 +19773,7 @@ msgid ""
 "Neither worked, so we gave up. You must fully qualify the ref."
 msgstr ""
 "La destination que vous avez fournie n'est pas un nom de référence complète\n"
-"(c'est-à-dire commençant par \"ref/\"). Essai d'approximation par :\n"
+"(c'est-à-dire commençant par \"refs/\"). Essai d'approximation par :\n"
 "\n"
 "- Recherche d'une référence qui correspond à '%s' sur le serveur distant.\n"
 "- Vérification si la <source> en cours de poussée ('%s')\n"
diff --git a/po/zh_CN.po b/po/zh_CN.po
index 86402725b2..eb47e8f9b7 100644
--- a/po/zh_CN.po
+++ b/po/zh_CN.po
@@ -13224,8 +13224,8 @@ msgid ""
 msgid_plural ""
 "Note: Some branches outside the refs/remotes/ hierarchy were not removed;\n"
 "to delete them, use:"
-msgstr[0] "注意：ref/remotes 层级之外的一个分支未被移除。要删除它，使用："
-msgstr[1] "注意：ref/remotes 层级之外的一些分支未被移除。要删除它们，使用："
+msgstr[0] "注意：refs/remotes 层级之外的一个分支未被移除。要删除它，使用："
+msgstr[1] "注意：refs/remotes 层级之外的一些分支未被移除。要删除它们，使用："
 
 #: builtin/remote.c
 #, c-format
diff --git a/po/zh_TW.po b/po/zh_TW.po
index f777a0596f..b2a79cdd93 100644
--- a/po/zh_TW.po
+++ b/po/zh_TW.po
@@ -13109,7 +13109,7 @@ msgid ""
 msgid_plural ""
 "Note: Some branches outside the refs/remotes/ hierarchy were not removed;\n"
 "to delete them, use:"
-msgstr[0] "注意：ref/remotes 層級之外的一個分支未被移除。要刪除它，使用："
+msgstr[0] "注意：refs/remotes 層級之外的一個分支未被移除。要刪除它，使用："
 
 #: builtin/remote.c
 #, c-format
diff --git a/t/t6300-for-each-ref.sh b/t/t6300-for-each-ref.sh
index 54e2281259..e68f7bec8e 100755
--- a/t/t6300-for-each-ref.sh
+++ b/t/t6300-for-each-ref.sh
@@ -841,7 +841,7 @@ test_expect_success 'err on bad describe atom arg' '
 		EOF
 		test_must_fail git for-each-ref \
 			--format="%(describe:tags,qux=1,abbrev=14)" \
-			ref/heads/master 2>actual &&
+			refs/heads/master 2>actual &&
 		test_cmp expect actual
 	)
 '


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> On Fri, Dec 15, 2023 at 02:28:00PM -0800, Junio C Hamano wrote:
>> There is no 'ref/notes/' hierarchy.  '[format] notes = foo' uses notes
>> that are found in 'refs/notes/foo'.
>> 
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>> ---
>>  * According to my eyeballing "git grep refs/ Documentation" result,
>>    this was the only remaining mention of "ref/" in Documentation/
>>    hierarchy that misspells "refs/".
>
> This made me look for additional instances where we were referring to
> "ref/". Turns out it's only a very limited set, see the below diff.

Yup, I did the same grep, but I tend to avoid churning what we
published long ago (and kept in Documentation/RelNotes/), my patches
only covered documents that are still relevant.

> the translation changes with a big grain of salt though,

Hopefully pinging Jiang would be sufficient to ask help from the
French, Chinese, and Taiwaneese translation teams.

> diff --git a/po/fr.po b/po/fr.po
> index ee2e610ef1..744550b056 100644
> --- a/po/fr.po
> +++ b/po/fr.po
> @@ -19773,7 +19773,7 @@ msgid ""
>  "Neither worked, so we gave up. You must fully qualify the ref."
>  msgstr ""
>  "La destination que vous avez fournie n'est pas un nom de référence complète\n"
> -"(c'est-à-dire commençant par \"ref/\"). Essai d'approximation par :\n"
> +"(c'est-à-dire commençant par \"refs/\"). Essai d'approximation par :\n"
>  "\n"
>  "- Recherche d'une référence qui correspond à '%s' sur le serveur distant.\n"
>  "- Vérification si la <source> en cours de poussée ('%s')\n"
> diff --git a/po/zh_CN.po b/po/zh_CN.po
> index 86402725b2..eb47e8f9b7 100644
> --- a/po/zh_CN.po
> +++ b/po/zh_CN.po
> @@ -13224,8 +13224,8 @@ msgid ""
>  msgid_plural ""
>  "Note: Some branches outside the refs/remotes/ hierarchy were not removed;\n"
>  "to delete them, use:"
> -msgstr[0] "注意：ref/remotes 层级之外的一个分支未被移除。要删除它，使用："
> -msgstr[1] "注意：ref/remotes 层级之外的一些分支未被移除。要删除它们，使用："
> +msgstr[0] "注意：refs/remotes 层级之外的一个分支未被移除。要删除它，使用："
> +msgstr[1] "注意：refs/remotes 层级之外的一些分支未被移除。要删除它们，使用："
>  
>  #: builtin/remote.c
>  #, c-format
> diff --git a/po/zh_TW.po b/po/zh_TW.po
> index f777a0596f..b2a79cdd93 100644
> --- a/po/zh_TW.po
> +++ b/po/zh_TW.po
> @@ -13109,7 +13109,7 @@ msgid ""
>  msgid_plural ""
>  "Note: Some branches outside the refs/remotes/ hierarchy were not removed;\n"
>  "to delete them, use:"
> -msgstr[0] "注意：ref/remotes 層級之外的一個分支未被移除。要刪除它，使用："
> +msgstr[0] "注意：refs/remotes 層級之外的一個分支未被移除。要刪除它，使用："
>  
>  #: builtin/remote.c
>  #, c-format

> Also, the test is
> interesting because it would fail even if we didn't pass an invalid atom
> to git-for-each-ref(1).

It is interesting but not surprising.  It is not an error to use ref
patterns that do not match any ref.  It is a mere pattern to filtering
what are in refs/ for the ones to be output.

> diff --git a/t/t6300-for-each-ref.sh b/t/t6300-for-each-ref.sh
> index 54e2281259..e68f7bec8e 100755
> --- a/t/t6300-for-each-ref.sh
> +++ b/t/t6300-for-each-ref.sh
> @@ -841,7 +841,7 @@ test_expect_success 'err on bad describe atom arg' '
>  		EOF
>  		test_must_fail git for-each-ref \
>  			--format="%(describe:tags,qux=1,abbrev=14)" \
> -			ref/heads/master 2>actual &&
> +			refs/heads/master 2>actual &&
>  		test_cmp expect actual
>  	)
>  '

The "for-each-ref" family's "--format" string is first parsed and
sanity-checked before it is applied.  The bogus ref pattern may not
yield any ref to apply the format string, but we do not optimize out
the parsing and checking, even though we could, as it would be
optimizing for a wrong case.  So regardless of the ref pattern at
the end of the command line does not make a difference to the
outcome of this test.

Re: [PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy

[Jiang Xin]

On Tue, Dec 19, 2023 at 12:16 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Patrick Steinhardt <ps@pks.im> writes:
> > the translation changes with a big grain of salt though,
>
> Hopefully pinging Jiang would be sufficient to ask help from the
> French, Chinese, and Taiwaneese translation teams.

The l10n team has a command line tool called git-po-helper that can
check for spelling errors in translations, such as mismatched command
names, configuration variables. A new pattern will be added to find
mismatched reference prefixes, and the following typos will be fixed
during the next localization window.

> > diff --git a/po/fr.po b/po/fr.po
> > index ee2e610ef1..744550b056 100644
> > --- a/po/fr.po
> > +++ b/po/fr.po
> > @@ -19773,7 +19773,7 @@ msgid ""
> >  "Neither worked, so we gave up. You must fully qualify the ref."
> >  msgstr ""
> >  "La destination que vous avez fournie n'est pas un nom de référence complète\n"
> > -"(c'est-à-dire commençant par \"ref/\"). Essai d'approximation par :\n"
> > +"(c'est-à-dire commençant par \"refs/\"). Essai d'approximation par :\n"
> >  "\n"
> >  "- Recherche d'une référence qui correspond à '%s' sur le serveur distant.\n"
> >  "- Vérification si la <source> en cours de poussée ('%s')\n"
> > diff --git a/po/zh_CN.po b/po/zh_CN.po
> > index 86402725b2..eb47e8f9b7 100644
> > --- a/po/zh_CN.po
> > +++ b/po/zh_CN.po
> > @@ -13224,8 +13224,8 @@ msgid ""
> >  msgid_plural ""
> >  "Note: Some branches outside the refs/remotes/ hierarchy were not removed;\n"
> >  "to delete them, use:"
> > -msgstr[0] "注意：ref/remotes 层级之外的一个分支未被移除。要删除它，使用："
> > -msgstr[1] "注意：ref/remotes 层级之外的一些分支未被移除。要删除它们，使用："
> > +msgstr[0] "注意：refs/remotes 层级之外的一个分支未被移除。要删除它，使用："
> > +msgstr[1] "注意：refs/remotes 层级之外的一些分支未被移除。要删除它们，使用："
> >
> >  #: builtin/remote.c
> >  #, c-format
> > diff --git a/po/zh_TW.po b/po/zh_TW.po
> > index f777a0596f..b2a79cdd93 100644
> > --- a/po/zh_TW.po
> > +++ b/po/zh_TW.po
> > @@ -13109,7 +13109,7 @@ msgid ""
> >  msgid_plural ""
> >  "Note: Some branches outside the refs/remotes/ hierarchy were not removed;\n"
> >  "to delete them, use:"
> > -msgstr[0] "注意：ref/remotes 層級之外的一個分支未被移除。要刪除它，使用："
> > +msgstr[0] "注意：refs/remotes 層級之外的一個分支未被移除。要刪除它，使用："
> >
> >  #: builtin/remote.c
> >  #, c-format

Re: [PATCH 1/5] git.txt: HEAD is not that special

[Ramsay Jones]

On 15/12/2023 22:19, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
>>
>>>> -may contain the SHA-1 name of an object or the name of another ref.  Refs
>>>> -with names beginning `ref/head/` contain the SHA-1 name of the most
>>>> +may contain the SHA-1 name of an object or the name of another ref (the
>>>> +latter is called a "symbolic ref").
>>>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>>>
>>> Hmm, s:ref/head:refs/heads: right?
>>
>> Yeah, right, not a new problem with this change, but is indeed a
>> good thing to catch and correct.  Thanks for a careful review.
> 
> And we have ref/tags/ just below, which I also have fixed locally.

Heh, yeah I missed that, along with 'ref/notes'. ;)

ATB,
Ramsay Jones

Re: [PATCH 1/5] git.txt: HEAD is not that special

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2364 bytes --]

On Fri, Dec 15, 2023 at 12:32:41PM -0800, Junio C Hamano wrote:
> The introductory text in "git help git" that describes HEAD called
> it "a special ref".  It is special compared to the more regular refs
> like refs/heads/master and refs/tags/v1.0.0, but not that special,
> unlike truly special ones like FETCH_HEAD.
> 
> Rewrite a few sentences to also introduce the distinction between a
> regular ref that contain the object name and a symbolic ref that
> contain the name of another ref.  Update the description of HEAD
> that point at the current branch to use the more correct term, a
> "symbolic ref".
> 
> This was found as part of auditing the documentation and in-code
> comments for uses of "special ref" that refer merely a "pseudo ref".
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/git.txt | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 2535a30194..880cdc5d7f 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for
>  efficiency may later be compressed together into "pack files".
>  
>  Named pointers called refs mark interesting points in history.  A ref
> -may contain the SHA-1 name of an object or the name of another ref.  Refs
> -with names beginning `ref/head/` contain the SHA-1 name of the most
> +may contain the SHA-1 name of an object or the name of another ref (the
> +latter is called a "symbolic ref").

On a tangent: While we have a name for symbolic refs, do we also have a
name for non-symbolic refs? I often use the term "direct ref" to clearly
distinguish them from symbolic refs, but it's of course not defined in
our glossary.

> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>  recent commit (or "head") of a branch under development.  SHA-1 names of
> -tags of interest are stored under `ref/tags/`.  A special ref named
> +tags of interest are stored under `ref/tags/`.  A symbolic ref named
>  `HEAD` contains the name of the currently checked-out branch.

I was briefly wondering whether we also want to replace SHA-1 with
"object hash" while at it, but it's certainly out of the scope of this
patch series.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/5] git.txt: HEAD is not that special

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

>>  Named pointers called refs mark interesting points in history.  A ref
>> -may contain the SHA-1 name of an object or the name of another ref.  Refs
>> -with names beginning `ref/head/` contain the SHA-1 name of the most
>> +may contain the SHA-1 name of an object or the name of another ref (the
>> +latter is called a "symbolic ref").
>
> On a tangent: While we have a name for symbolic refs, do we also have a
> name for non-symbolic refs? I often use the term "direct ref" to clearly
> distinguish them from symbolic refs, but it's of course not defined in
> our glossary.

You may find me saying "normal ref", "regular ref", or somesuch when
it is not clear from the context if you dig the list archive.
"direct" is a nice word, especially it would give us a good pair of
terms if we are to change "symbolic" to "indirect", but since we are
not going to do so, I am not sure the contrast between "direct" and
"symbolic" would make such a good pair.

But quite honestly I rarely felt a need for a specific term, as it
is fairly clear from the context, e.g.

 * "From a ref, we locate an object using the object name it
   records and use the object"

   A statement written from the point of view of the consumer of
   object name, it does not matter if the object name is directly
   found in the ref, or indirection is involved to find such a
   concrete ref that records an object name by following the
   original symbolic ref.

 * "A ref usually stores an object name, but it can also be a
   symbolic ref that points at another ref, in which case, asking
   what object such a symbolic ref points at would yield the object
   the other ref points at".

So I dunno.

>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>>  recent commit (or "head") of a branch under development.  SHA-1 names of
>> -tags of interest are stored under `ref/tags/`.  A special ref named
>> +tags of interest are stored under `ref/tags/`.  A symbolic ref named
>>  `HEAD` contains the name of the currently checked-out branch.
>
> I was briefly wondering whether we also want to replace SHA-1 with
> "object hash" while at it, but it's certainly out of the scope of this
> patch series.

Yup, there still are too many reference to SHA-1 (and "sha1", which
is even worse), and it is not a focus of this series.

Thanks.

[PATCH 2/5] git-bisect.txt: BISECT_HEAD is not that special

[Junio C Hamano]

The description of "git bisect --no-checkout" called BISECT_HEAD a
"special ref", but there is nothing special about it.  It merely is
yet another pseudoref.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-bisect.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 191b4a42b6..aa02e46224 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -362,7 +362,7 @@ OPTIONS
 --no-checkout::
 +
 Do not checkout the new working tree at each iteration of the bisection
-process. Instead just update a special reference named `BISECT_HEAD` to make
+process. Instead just update the reference named `BISECT_HEAD` to make
 it point to the commit that should be tested.
 +
 This option may be useful when the test you would perform in each step
-- 
2.43.0-76-g1a87c842ec

[PATCH 3/5] refs.h: HEAD is not that special

[Junio C Hamano]

In-code comment explains pseudorefs but used a wrong nomenclature
"special ref".

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 refs.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/refs.h b/refs.h
index 23211a5ea1..ff113bb12a 100644
--- a/refs.h
+++ b/refs.h
@@ -56,7 +56,7 @@ struct worktree;
  * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/
  * directory and do not consist of all caps and underscores cannot be
  * resolved. The function returns NULL for such ref names.
- * Caps and underscores refers to the special refs, such as HEAD,
+ * Caps and underscores refers to the pseudorefs, such as HEAD,
  * FETCH_HEAD and friends, that all live outside of the refs/ directory.
  */
 #define RESOLVE_REF_READING 0x01
-- 
2.43.0-76-g1a87c842ec

Re: [PATCH 3/5] refs.h: HEAD is not that special

[Andy Koppe]

On 15/12/2023 20:32, Junio C Hamano wrote:
> In-code comment explains pseudorefs but used a wrong nomenclature
> "special ref".
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>   refs.h | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/refs.h b/refs.h
> index 23211a5ea1..ff113bb12a 100644
> --- a/refs.h
> +++ b/refs.h
> @@ -56,7 +56,7 @@ struct worktree;
>    * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/
>    * directory and do not consist of all caps and underscores cannot be
>    * resolved. The function returns NULL for such ref names.
> - * Caps and underscores refers to the special refs, such as HEAD,
> + * Caps and underscores refers to the pseudorefs, such as HEAD,
>    * FETCH_HEAD and friends, that all live outside of the refs/ directory.
>    */
>   #define RESOLVE_REF_READING 0x01

gitglossary thinks that HEAD is not a pseudoref:

"Pseudorefs are a class of files under $GIT_DIR which behave like refs 
for the purposes of rev-parse, but which are treated specially by git. 
Pseudorefs both have names that are all-caps, and always start with a 
line consisting of a SHA‐1 followed by whitespace. So, HEAD is not a 
pseudoref, because it is sometimes a symbolic ref."

(Also, the "sometimes" there actually is "whenever you're on a branch", 
which is most of the time for most people.)

Regards,
Andy

[PATCH 4/5] docs: AUTO_MERGE is not that special

[Junio C Hamano]

A handful of manual pages called AUTO_MERGE a "special ref", but
there is nothing special about it.  It merely is yet another
pseudoref.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-diff.txt    | 2 +-
 Documentation/git-merge.txt   | 2 +-
 Documentation/user-manual.txt | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 08087ffad5..c065f023ec 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -103,7 +103,7 @@ Just in case you are doing something exotic, it should be
 noted that all of the <commit> in the above description, except
 in the `--merge-base` case and in the last two forms that use `..`
 notations, can be any <tree>. A tree of interest is the one pointed to
-by the special ref `AUTO_MERGE`, which is written by the 'ort' merge
+by the ref named `AUTO_MERGE`, which is written by the 'ort' merge
 strategy upon hitting merge conflicts (see linkgit:git-merge[1]).
 Comparing the working tree with `AUTO_MERGE` shows changes you've made
 so far to resolve textual conflicts (see the examples below).
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e8ab340319..3e9557a44b 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -196,7 +196,7 @@ happens:
    can inspect the stages with `git ls-files -u`).  The working
    tree files contain the result of the merge operation; i.e. 3-way
    merge results with familiar conflict markers `<<<` `===` `>>>`.
-5. A special ref `AUTO_MERGE` is written, pointing to a tree
+5. A ref named `AUTO_MERGE` is written, pointing to a tree
    corresponding to the current content of the working tree (including
    conflict markers for textual conflicts).  Note that this ref is only
    written when the 'ort' merge strategy is used (the default).
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index d8dbe6b56d..5d32ff2384 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1344,7 +1344,7 @@ $ git diff --theirs file.txt	# same as the above.
 -------------------------------------------------
 
 When using the 'ort' merge strategy (the default), before updating the working
-tree with the result of the merge, Git writes a special ref named AUTO_MERGE
+tree with the result of the merge, Git writes a ref named AUTO_MERGE
 reflecting the state of the tree it is about to write. Conflicted paths with
 textual conflicts that could not be automatically merged are written to this
 tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be
-- 
2.43.0-76-g1a87c842ec

[PATCH 5/5] docs: MERGE_AUTOSTASH is not that special

[Junio C Hamano]

A handful of manual pages called MERGE_AUTOSTASH a "special ref",
but there is nothing special about it.  It merely is yet another
pseudoref.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/merge-options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index d8f7cd7ca0..3eaefc4e94 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -191,7 +191,7 @@ endif::git-pull[]
 --autostash::
 --no-autostash::
 	Automatically create a temporary stash entry before the operation
-	begins, record it in the special ref `MERGE_AUTOSTASH`
+	begins, record it in the ref `MERGE_AUTOSTASH`
 	and apply it after the operation ends.  This means
 	that you can run the operation on a dirty worktree.  However, use
 	with care: the final stash application after a successful
-- 
2.43.0-76-g1a87c842ec

Re: [PATCH 5/5] docs: MERGE_AUTOSTASH is not that special

[Andy Koppe]

On 15/12/2023 20:32, Junio C Hamano wrote:
> A handful of manual pages called MERGE_AUTOSTASH a "special ref",
> but there is nothing special about it.  It merely is yet another
> pseudoref.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>   Documentation/merge-options.txt | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index d8f7cd7ca0..3eaefc4e94 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -191,7 +191,7 @@ endif::git-pull[]
>   --autostash::
>   --no-autostash::
>   	Automatically create a temporary stash entry before the operation
> -	begins, record it in the special ref `MERGE_AUTOSTASH`
> +	begins, record it in the ref `MERGE_AUTOSTASH`
>   	and apply it after the operation ends.  This means
>   	that you can run the operation on a dirty worktree.  However, use
>   	with care: the final stash application after a successful

Should that say 'pseudoref' instead of 'ref'?

And since MERGE_AUTOSTASH is documented here, it probably should be in 
gitrevisions as well.

Regards,
Andy

Re: [PATCH 0/5] make room for "special ref"

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> ...  For example, FETCH_HEAD currently stores not
> just a single object name, but can and is used to store multiple
> object names, each with annotations to record where they came from.
> There indeed may be a need to introduce a new term to refer to such
> "special refs".

The "may be" here vaguely hints another possibility.  If we manage
to get rid of the "special refs", we do not even have to mention
"special refs", and more importantly, we do not need extra code to
deal with them.

For FETCH_HEAD, for example, I wonder if an update along this line
is possible:

 * Teach "git fetch" to store what it writes to FETCH_HEAD to a
   different file, under a distinctly different filename (e.g.,
   $GIT_DIR/fetched-tips).  Demote FETCH_HEAD to a pseudoref, and
   store the first object name in that "fetched-tips" file to it.

 * Teach "git pull" to learn what it used to learn from FETCH_HEAD
   (i.e., list of fetched tips, each annotated with what ref at what
   repository it came from and if it is to be merged) from the new
   "fetched-tips" file.

The "special" ness of FETCH_HEAD is really an implementation detail
of how "git pull" works and how the findings of "git fetch" are
communicated to "git pull".  The general refs API should not have to
worry about it, and the refs backends should not have to worry about
storing more than just an object name (or if it is a symbolic ref,
the target refname).

An end-user command like "git log ORIG_HEAD..FETCH_HEAD" would not
be affected by changes along the above line, because the current
FETCH_HEAD, when used as a revision, will work as if it stores the
single object name that is listed first in the file.

If somebody is reading FETCH_HEAD and acting on its contents (rather
than merely consuming it as a ref of the first object), perhaps
feeding it to "git fmt-merge-msg", they will be broken by such a
change (indeed, our own "git pull" will be broken by the change to
"git fetch", and the second bullet point above is about fixing the
exact fallout from it), but I am not sure if that is a use case worth
worrying about.

Hmm?

Re: [PATCH 0/5] make room for "special ref"

[Ramsay Jones]

On 15/12/2023 21:21, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> ...  For example, FETCH_HEAD currently stores not
>> just a single object name, but can and is used to store multiple
>> object names, each with annotations to record where they came from.
>> There indeed may be a need to introduce a new term to refer to such
>> "special refs".
> 
> The "may be" here vaguely hints another possibility.  If we manage
> to get rid of the "special refs", we do not even have to mention
> "special refs", and more importantly, we do not need extra code to
> deal with them.
> 
> For FETCH_HEAD, for example, I wonder if an update along this line
> is possible:
> 
>  * Teach "git fetch" to store what it writes to FETCH_HEAD to a
>    different file, under a distinctly different filename (e.g.,
>    $GIT_DIR/fetched-tips).  Demote FETCH_HEAD to a pseudoref, and
>    store the first object name in that "fetched-tips" file to it.
> 
>  * Teach "git pull" to learn what it used to learn from FETCH_HEAD
>    (i.e., list of fetched tips, each annotated with what ref at what
>    repository it came from and if it is to be merged) from the new
>    "fetched-tips" file.
> 
> The "special" ness of FETCH_HEAD is really an implementation detail
> of how "git pull" works and how the findings of "git fetch" are
> communicated to "git pull".  The general refs API should not have to
> worry about it, and the refs backends should not have to worry about
> storing more than just an object name (or if it is a symbolic ref,
> the target refname).
> 
> An end-user command like "git log ORIG_HEAD..FETCH_HEAD" would not
> be affected by changes along the above line, because the current
> FETCH_HEAD, when used as a revision, will work as if it stores the
> single object name that is listed first in the file.
> 
> If somebody is reading FETCH_HEAD and acting on its contents (rather
> than merely consuming it as a ref of the first object), perhaps
> feeding it to "git fmt-merge-msg", they will be broken by such a
> change (indeed, our own "git pull" will be broken by the change to
> "git fetch", and the second bullet point above is about fixing the
> exact fallout from it), but I am not sure if that is a use case worth
> worrying about.
> 
> Hmm?
> 

Yes, I was going to suggest exactly this, after Patrick pointed out
that there were only two 'special psuedo-refs' (I had a vague feeling
there were some more than that) FETCH_HEAD and MERGE_HEAD.

ATB,
Ramsay Jones

Re: [PATCH 0/5] make room for "special ref"

[Junio C Hamano]

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

> Yes, I was going to suggest exactly this, after Patrick pointed out
> that there were only two 'special psuedo-refs' (I had a vague feeling
> there were some more than that) FETCH_HEAD and MERGE_HEAD.

Glad to see that I am not alone.  We should be able to treat
MERGE_HEAD similarly.  It is used to communicate the list of "other
parents" from "git merge" that stops in the middle (either for merge
conflict, or in response to the "--no-commit" command line option)
to "git commit" that concludes such an unfinished merge.  Many
commands merely use the presence of MERGE_HEAD as a sign that a
merge is in progress (e.g. "git status"), which would not break if
we just started to record the first parent in a pseudoref MERGE_HEAD
and wrote the other octopus parents elsewhere, but some commands do
need all these parents from MERGE_HEAD (e.g. "git blame" that
synthesizes a fake starting commit out of the working tree state).

If we cannot get rid of all "special refs" anyway, however, I think
there is little that we can gain from doing such "make FETCH_HEAD
and MERGE_HEAD into a single-object pseudoref, and write other info
in separate files" exercise.  We can treat the current FETCH_HEAD
and MERGE_HEAD as "file that is not and is more than a ref", which
is what the current code is doing anyway, which means we would
declare that they have to stay to be files under $GIT_DIR/ and will
be accessed via the filesystem access.  At that point, calling them
"special ref" might even be more misleading than its worth and we
may be better off to admit that they are not even refs but a
datafile some commands can use to obtain input from, but the phrase
we use to refer to them, be it "special ref" or some random
datafile, does not make a fundamental change on anything.

Re: [PATCH 0/5] make room for "special ref"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 4024 bytes --]

On Fri, Dec 15, 2023 at 04:44:47PM -0800, Junio C Hamano wrote:
> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
> 
> > Yes, I was going to suggest exactly this, after Patrick pointed out
> > that there were only two 'special psuedo-refs' (I had a vague feeling
> > there were some more than that) FETCH_HEAD and MERGE_HEAD.

I don't think there are more special refs than those two. Andy pointed
out CHERRY_PICK_HEAD and REVERT_HEAD, but both of them actually get
accessed via the ref backend exclusively and thus cannot be special in
any way. Also, the test suite of Git passes with only those two refs
marked as special refs with the reftable backend, which is another good
indicator that I didn't miss anything here because we definitely can't
store special information in the reftable backend.

It's of course still possible that our test suite has a blind spot and
that I missed any special refs. If so, I would love to hear about them.

> Glad to see that I am not alone.  We should be able to treat
> MERGE_HEAD similarly.  It is used to communicate the list of "other
> parents" from "git merge" that stops in the middle (either for merge
> conflict, or in response to the "--no-commit" command line option)
> to "git commit" that concludes such an unfinished merge.  Many
> commands merely use the presence of MERGE_HEAD as a sign that a
> merge is in progress (e.g. "git status"), which would not break if
> we just started to record the first parent in a pseudoref MERGE_HEAD
> and wrote the other octopus parents elsewhere, but some commands do
> need all these parents from MERGE_HEAD (e.g. "git blame" that
> synthesizes a fake starting commit out of the working tree state).

I would certainly love to drop the "specialness" of both FETCH_HEAD and
MERGE_HEAD, but I am a bit pessimistic about whether we really can. The
format of those refs has been around for quite a long time already, and
I do expect that there is tooling out there that parses those files.

I would claim that it's especially likely that FETCH_HEAD is getting
parsed by external tools. Historically, there has not been a way to
really figure out which refs have been updated in git-fetch(1). So any
scripts that perform a fetch and want to learn about what was updated
would very likely resort to parsing FETCH_HEAD. This has changed a bit
with the introduction of the machine-parsable interface of git-fetch(1),
but it has only been introduced rather recently with Git v2.42.

> If we cannot get rid of all "special refs" anyway, however, I think
> there is little that we can gain from doing such "make FETCH_HEAD
> and MERGE_HEAD into a single-object pseudoref, and write other info
> in separate files" exercise.  We can treat the current FETCH_HEAD
> and MERGE_HEAD as "file that is not and is more than a ref", which
> is what the current code is doing anyway, which means we would
> declare that they have to stay to be files under $GIT_DIR/ and will
> be accessed via the filesystem access.

I'd like for it to be otherwise, but I think this is the only sensible
thing to do. I think it was a mistake to introduce those special refs
like this and treat them almost like a real ref, but that's always easy
to say in hindsight.

> At that point, calling them "special ref" might even be more
> misleading than its worth and we may be better off to admit that they
> are not even refs but a datafile some commands can use to obtain input
> from, but the phrase we use to refer to them, be it "special ref" or
> some random datafile, does not make a fundamental change on anything.

Well, the problem is that these do indeed behave like a ref for most of
the part: you can ask for them via git-rev-parse(1) and we'll resolve
them just fine, even though we only ever return the first object ID. So
even though I'm not a huge fan of calling them "special ref", I think we
should at least highlight the reflike-nature in whatever we want to call
them.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 0/5] make room for "special ref"

[Andy Koppe]

On 15/12/2023 22:44, Ramsay Jones wrote:
> On 15/12/2023 21:21, Junio C Hamano wrote:

>> If somebody is reading FETCH_HEAD and acting on its contents (rather
>> than merely consuming it as a ref of the first object), perhaps
>> feeding it to "git fmt-merge-msg", they will be broken by such a
>> change (indeed, our own "git pull" will be broken by the change to
>> "git fetch", and the second bullet point above is about fixing the
>> exact fallout from it), but I am not sure if that is a use case worth
>> worrying about.
> 
> Yes, I was going to suggest exactly this, after Patrick pointed out
> that there were only two 'special psuedo-refs' (I had a vague feeling
> there were some more than that) FETCH_HEAD and MERGE_HEAD.

According to the pseudoref entry of gitglossary, CHERRY_PICK_HEAD also 
stores additional data (which would imply that REVERT_HEAD does too).
Looking at CHERRY_PICK_HEAD during a pick though, I only see a single 
hash, even when picking multiple commits.

Regards,
Andy

Re: [PATCH 0/5] make room for "special ref"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1323 bytes --]

On Sat, Dec 16, 2023 at 10:20:09AM +0000, Andy Koppe wrote:
> On 15/12/2023 22:44, Ramsay Jones wrote:
> > On 15/12/2023 21:21, Junio C Hamano wrote:
> 
> > > If somebody is reading FETCH_HEAD and acting on its contents (rather
> > > than merely consuming it as a ref of the first object), perhaps
> > > feeding it to "git fmt-merge-msg", they will be broken by such a
> > > change (indeed, our own "git pull" will be broken by the change to
> > > "git fetch", and the second bullet point above is about fixing the
> > > exact fallout from it), but I am not sure if that is a use case worth
> > > worrying about.
> > 
> > Yes, I was going to suggest exactly this, after Patrick pointed out
> > that there were only two 'special psuedo-refs' (I had a vague feeling
> > there were some more than that) FETCH_HEAD and MERGE_HEAD.
> 
> According to the pseudoref entry of gitglossary, CHERRY_PICK_HEAD also
> stores additional data (which would imply that REVERT_HEAD does too).
> Looking at CHERRY_PICK_HEAD during a pick though, I only see a single hash,
> even when picking multiple commits.

Both CHERRY_PICK_HEAD and REVERT_HEAD are only ever updated via the refs
API, so neither of them ever contains anything other than a normal ref.
I guess we should update the glossary accordingly.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 0/5] make room for "special ref"

[Andy Koppe]

On 15/12/2023 20:32, Junio C Hamano wrote:
> A pseudo ref is merely a normal ref with a funny naming convention,
> i.e., being outside the refs/ hierarchy and has names with all
> uppercase letters (or an underscore).

I know what you mean, but gitglossary defines pseudorefs as separate 
from refs, albeit behaving like refs. Their name itself implies the same.

Although the 'ref' entry then goes on to say that "there are a few 
special-purpose refs that do not begin with 'refs/', the most notable 
example being HEAD."

That implies that at least some of the pseudorefs are refs after all, 
while keeping in mind that "HEAD is not a pseudoref,  because it is 
sometimes a symbolic ref" according to the 'pseudoref' entry.

I think a clearer answer on whether pseudorefs are refs is needed, or at 
least a better-defined fudge, such as "pseudorefs are refs except when ...".

Defining everything under "refs/" as refs, and the stuff outside it 
including HEAD itself as pseudorefs, would draw clearer lines. The fact 
HEAD is usually symbolic doesn't seem all that relevant from the 
perspective of a user trying to get a grasp of refs and pseudorefs.

Regards,
Andy

Re: [PATCH 0/5] make room for "special ref"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1832 bytes --]

On Fri, Dec 15, 2023 at 12:32:40PM -0800, Junio C Hamano wrote:
> Patrick's reftable work is progressing nicely and wants to establish
> "special ref" as a phrase with some defined meaning that is somewhat
> different from a mere "pseudo ref".
> 
> A pseudo ref is merely a normal ref with a funny naming convention,
> i.e., being outside the refs/ hierarchy and has names with all
> uppercase letters (or an underscore).  But there truly are refs that
> are more than that.  For example, FETCH_HEAD currently stores not
> just a single object name, but can and is used to store multiple
> object names, each with annotations to record where they came from.
> There indeed may be a need to introduce a new term to refer to such
> "special refs".
> 
> Existing documentation, however, uses "special ref" to refer to
> pseudo refs without any "special" property, like FETCH_HEAD does.
> 
> This series merely corrects such existing uses of the word, to make
> room for Patrick's series to introduce (and formally define in the
> glossary) "special refs".

Thanks for helping out with this effort and kicking off the discussion,
I highly appreciate it!

Patrick

> Junio C Hamano (5):
>   git.txt: HEAD is not that special
>   git-bisect.txt: BISECT_HEAD is not that special
>   refs.h: HEAD is not that special
>   docs: AUTO_MERGE is not that special
>   docs: MERGE_AUTOSTASH is not that special
> 
>  Documentation/git-bisect.txt    | 2 +-
>  Documentation/git-diff.txt      | 2 +-
>  Documentation/git-merge.txt     | 2 +-
>  Documentation/git.txt           | 7 ++++---
>  Documentation/merge-options.txt | 2 +-
>  Documentation/user-manual.txt   | 2 +-
>  refs.h                          | 2 +-
>  7 files changed, 10 insertions(+), 9 deletions(-)
> 
> -- 
> 2.43.0-76-g1a87c842ec
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]