{"thread":{"id":"60619","subject":"[PATCH 2/5] git-bisect.txt: BISECT_HEAD is not that special","startedAt":"2023-12-15T20:32:55Z","lastAt":"2023-12-19T15:33:15Z","messageCount":26,"participants":["Junio C Hamano","Ramsay Jones","Andy Koppe","Patrick Steinhardt","Jiang Xin"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"485723","messageId":"20231215203245.3622299-3-gitster@pobox.com","threadId":"60619","inReplyTo":"20231215203245.3622299-1-gitster@pobox.com","subject":"[PATCH 2/5] git-bisect.txt: BISECT_HEAD is not that special","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T20:32:42Z","receivedAt":"2023-12-15T20:32:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The description of \"git bisect --no-checkout\" called BISECT_HEAD a\n\"special ref\", but there is nothing special about it. It merely is\nyet another pseudoref.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-bisect.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex 191b4a42b6..aa02e46224 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -362,7 +362,7 @@ OPTIONS\n --no-checkout::\n +\n Do not checkout the new working tree at each iteration of the bisection\n-process. Instead just update a special reference named `BISECT_HEAD` to make\n+process. Instead just update the reference named `BISECT_HEAD` to make\n it point to the commit that should be tested.\n +\n This option may be useful when the test you would perform in each step\n-- \n2.43.0-76-g1a87c842ec\n\n"},{"id":"485724","messageId":"20231215203245.3622299-1-gitster@pobox.com","threadId":"60619","inReplyTo":null,"subject":"[PATCH 0/5] make room for \"special ref\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T20:32:40Z","receivedAt":"2023-12-15T20:32:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick's reftable work is progressing nicely and wants to establish\n\"special ref\" as a phrase with some defined meaning that is somewhat\ndifferent from a mere \"pseudo ref\".\n\nA pseudo ref is merely a normal ref with a funny naming convention,\ni.e., being outside the refs/ hierarchy and has names with all\nuppercase letters (or an underscore). But there truly are refs that\nare more than that. For example, FETCH_HEAD currently stores not\njust a single object name, but can and is used to store multiple\nobject names, each with annotations to record where they came from.\nThere indeed may be a need to introduce a new term to refer to such\n\"special refs\".\n\nExisting documentation, however, uses \"special ref\" to refer to\npseudo refs without any \"special\" property, like FETCH_HEAD does.\n\nThis series merely corrects such existing uses of the word, to make\nroom for Patrick's series to introduce (and formally define in the\nglossary) \"special refs\".\n\nJunio C Hamano (5):\n git.txt: HEAD is not that special\n git-bisect.txt: BISECT_HEAD is not that special\n refs.h: HEAD is not that special\n docs: AUTO_MERGE is not that special\n docs: MERGE_AUTOSTASH is not that special\n\n Documentation/git-bisect.txt | 2 +-\n Documentation/git-diff.txt | 2 +-\n Documentation/git-merge.txt | 2 +-\n Documentation/git.txt | 7 ++++---\n Documentation/merge-options.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n refs.h | 2 +-\n 7 files changed, 10 insertions(+), 9 deletions(-)\n\n-- \n2.43.0-76-g1a87c842ec\n\n"},{"id":"485725","messageId":"20231215203245.3622299-2-gitster@pobox.com","threadId":"60619","inReplyTo":"20231215203245.3622299-1-gitster@pobox.com","subject":"[PATCH 1/5] git.txt: HEAD is not that special","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T20:32:41Z","receivedAt":"2023-12-15T20:32:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The introductory text in \"git help git\" that describes HEAD called\nit \"a special ref\". It is special compared to the more regular refs\nlike refs/heads/master and refs/tags/v1.0.0, but not that special,\nunlike truly special ones like FETCH_HEAD.\n\nRewrite a few sentences to also introduce the distinction between a\nregular ref that contain the object name and a symbolic ref that\ncontain the name of another ref. Update the description of HEAD\nthat point at the current branch to use the more correct term, a\n\"symbolic ref\".\n\nThis was found as part of auditing the documentation and in-code\ncomments for uses of \"special ref\" that refer merely a \"pseudo ref\".\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git.txt | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 2535a30194..880cdc5d7f 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for\n efficiency may later be compressed together into \"pack files\".\n \n Named pointers called refs mark interesting points in history. A ref\n-may contain the SHA-1 name of an object or the name of another ref. Refs\n-with names beginning `ref/head/` contain the SHA-1 name of the most\n+may contain the SHA-1 name of an object or the name of another ref (the\n+latter is called a \"symbolic ref\").\n+Refs with names beginning `ref/head/` contain the SHA-1 name of the most\n recent commit (or \"head\") of a branch under development. SHA-1 names of\n-tags of interest are stored under `ref/tags/`. A special ref named\n+tags of interest are stored under `ref/tags/`. A symbolic ref named\n `HEAD` contains the name of the currently checked-out branch.\n \n The index file is initialized with a list of all paths and, for each\n-- \n2.43.0-76-g1a87c842ec\n\n"},{"id":"485726","messageId":"20231215203245.3622299-4-gitster@pobox.com","threadId":"60619","inReplyTo":"20231215203245.3622299-1-gitster@pobox.com","subject":"[PATCH 3/5] refs.h: HEAD is not that special","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T20:32:43Z","receivedAt":"2023-12-15T20:32:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"In-code comment explains pseudorefs but used a wrong nomenclature\n\"special ref\".\n\nSigned-off-by: Junio C Hamano \n---\n refs.h | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/refs.h b/refs.h\nindex 23211a5ea1..ff113bb12a 100644\n--- a/refs.h\n+++ b/refs.h\n@@ -56,7 +56,7 @@ struct worktree;\n * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/\n * directory and do not consist of all caps and underscores cannot be\n * resolved. The function returns NULL for such ref names.\n- * Caps and underscores refers to the special refs, such as HEAD,\n+ * Caps and underscores refers to the pseudorefs, such as HEAD,\n * FETCH_HEAD and friends, that all live outside of the refs/ directory.\n */\n #define RESOLVE_REF_READING 0x01\n-- \n2.43.0-76-g1a87c842ec\n\n"},{"id":"485727","messageId":"20231215203245.3622299-5-gitster@pobox.com","threadId":"60619","inReplyTo":"20231215203245.3622299-1-gitster@pobox.com","subject":"[PATCH 4/5] docs: AUTO_MERGE is not that special","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T20:32:44Z","receivedAt":"2023-12-15T20:33:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"A handful of manual pages called AUTO_MERGE a \"special ref\", but\nthere is nothing special about it. It merely is yet another\npseudoref.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-diff.txt | 2 +-\n Documentation/git-merge.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 08087ffad5..c065f023ec 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -103,7 +103,7 @@ Just in case you are doing something exotic, it should be\n noted that all of the in the above description, except\n in the `--merge-base` case and in the last two forms that use `..`\n notations, can be any . A tree of interest is the one pointed to\n-by the special ref `AUTO_MERGE`, which is written by the 'ort' merge\n+by the ref named `AUTO_MERGE`, which is written by the 'ort' merge\n strategy upon hitting merge conflicts (see linkgit:git-merge[1]).\n Comparing the working tree with `AUTO_MERGE` shows changes you've made\n so far to resolve textual conflicts (see the examples below).\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex e8ab340319..3e9557a44b 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -196,7 +196,7 @@ happens:\n can inspect the stages with `git ls-files -u`). The working\n tree files contain the result of the merge operation; i.e. 3-way\n merge results with familiar conflict markers `<<<` `===` `>>>`.\n-5. A special ref `AUTO_MERGE` is written, pointing to a tree\n+5. A ref named `AUTO_MERGE` is written, pointing to a tree\n corresponding to the current content of the working tree (including\n conflict markers for textual conflicts). Note that this ref is only\n written when the 'ort' merge strategy is used (the default).\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex d8dbe6b56d..5d32ff2384 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1344,7 +1344,7 @@ $ git diff --theirs file.txt\t# same as the above.\n -------------------------------------------------\n \n When using the 'ort' merge strategy (the default), before updating the working\n-tree with the result of the merge, Git writes a special ref named AUTO_MERGE\n+tree with the result of the merge, Git writes a ref named AUTO_MERGE\n reflecting the state of the tree it is about to write. Conflicted paths with\n textual conflicts that could not be automatically merged are written to this\n tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be\n-- \n2.43.0-76-g1a87c842ec\n\n"},{"id":"485728","messageId":"20231215203245.3622299-6-gitster@pobox.com","threadId":"60619","inReplyTo":"20231215203245.3622299-1-gitster@pobox.com","subject":"[PATCH 5/5] docs: MERGE_AUTOSTASH is not that special","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T20:32:45Z","receivedAt":"2023-12-15T20:33:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"A handful of manual pages called MERGE_AUTOSTASH a \"special ref\",\nbut there is nothing special about it. It merely is yet another\npseudoref.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/merge-options.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt\nindex d8f7cd7ca0..3eaefc4e94 100644\n--- a/Documentation/merge-options.txt\n+++ b/Documentation/merge-options.txt\n@@ -191,7 +191,7 @@ endif::git-pull[]\n --autostash::\n --no-autostash::\n \tAutomatically create a temporary stash entry before the operation\n-\tbegins, record it in the special ref `MERGE_AUTOSTASH`\n+\tbegins, record it in the ref `MERGE_AUTOSTASH`\n \tand apply it after the operation ends. This means\n \tthat you can run the operation on a dirty worktree. However, use\n \twith care: the final stash application after a successful\n-- \n2.43.0-76-g1a87c842ec\n\n"},{"id":"485733","messageId":"xmqq5y0zkvqx.fsf@gitster.g","threadId":"60619","inReplyTo":"20231215203245.3622299-1-gitster@pobox.com","subject":"Re: [PATCH 0/5] make room for \"special ref\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T21:21:10Z","receivedAt":"2023-12-15T21:21:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> ... For example, FETCH_HEAD currently stores not\n> just a single object name, but can and is used to store multiple\n> object names, each with annotations to record where they came from.\n> There indeed may be a need to introduce a new term to refer to such\n> \"special refs\".\n\nThe \"may be\" here vaguely hints another possibility. If we manage\nto get rid of the \"special refs\", we do not even have to mention\n\"special refs\", and more importantly, we do not need extra code to\ndeal with them.\n\nFor FETCH_HEAD, for example, I wonder if an update along this line\nis possible:\n\n * Teach \"git fetch\" to store what it writes to FETCH_HEAD to a\n different file, under a distinctly different filename (e.g.,\n $GIT_DIR/fetched-tips). Demote FETCH_HEAD to a pseudoref, and\n store the first object name in that \"fetched-tips\" file to it.\n\n * Teach \"git pull\" to learn what it used to learn from FETCH_HEAD\n (i.e., list of fetched tips, each annotated with what ref at what\n repository it came from and if it is to be merged) from the new\n \"fetched-tips\" file.\n\nThe \"special\" ness of FETCH_HEAD is really an implementation detail\nof how \"git pull\" works and how the findings of \"git fetch\" are\ncommunicated to \"git pull\". The general refs API should not have to\nworry about it, and the refs backends should not have to worry about\nstoring more than just an object name (or if it is a symbolic ref,\nthe target refname).\n\nAn end-user command like \"git log ORIG_HEAD..FETCH_HEAD\" would not\nbe affected by changes along the above line, because the current\nFETCH_HEAD, when used as a revision, will work as if it stores the\nsingle object name that is listed first in the file.\n\nIf somebody is reading FETCH_HEAD and acting on its contents (rather\nthan merely consuming it as a ref of the first object), perhaps\nfeeding it to \"git fmt-merge-msg\", they will be broken by such a\nchange (indeed, our own \"git pull\" will be broken by the change to\n\"git fetch\", and the second bullet point above is about fixing the\nexact fallout from it), but I am not sure if that is a use case worth\nworrying about.\n\nHmm?\n"},{"id":"485734","messageId":"0c93d426-17c3-434c-bbd0-866c31c23f9d@ramsayjones.plus.com","threadId":"60619","inReplyTo":"20231215203245.3622299-2-gitster@pobox.com","subject":"Re: [PATCH 1/5] git.txt: HEAD is not that special","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2023-12-15T21:57:11Z","receivedAt":"2023-12-15T22:00:22Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 15/12/2023 20:32, Junio C Hamano wrote:\n> The introductory text in \"git help git\" that describes HEAD called\n> it \"a special ref\". It is special compared to the more regular refs\n> like refs/heads/master and refs/tags/v1.0.0, but not that special,\n> unlike truly special ones like FETCH_HEAD.\n> \n> Rewrite a few sentences to also introduce the distinction between a\n> regular ref that contain the object name and a symbolic ref that\n> contain the name of another ref. Update the description of HEAD\n> that point at the current branch to use the more correct term, a\n> \"symbolic ref\".\n> \n> This was found as part of auditing the documentation and in-code\n> comments for uses of \"special ref\" that refer merely a \"pseudo ref\".\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git.txt | 7 ++++---\n> 1 file changed, 4 insertions(+), 3 deletions(-)\n> \n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index 2535a30194..880cdc5d7f 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for\n> efficiency may later be compressed together into \"pack files\".\n> \n> Named pointers called refs mark interesting points in history. A ref\n> -may contain the SHA-1 name of an object or the name of another ref. Refs\n> -with names beginning `ref/head/` contain the SHA-1 name of the most\n> +may contain the SHA-1 name of an object or the name of another ref (the\n> +latter is called a \"symbolic ref\").\n> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most\n\nHmm, s:ref/head:refs/heads: right?\n\n> recent commit (or \"head\") of a branch under development. SHA-1 names of\n> -tags of interest are stored under `ref/tags/`. A special ref named\n> +tags of interest are stored under `ref/tags/`. A symbolic ref named\n> `HEAD` contains the name of the currently checked-out branch.\n> \n> The index file is initialized with a list of all paths and, for each\n"},{"id":"485735","messageId":"xmqq1qbnktnl.fsf@gitster.g","threadId":"60619","inReplyTo":"0c93d426-17c3-434c-bbd0-866c31c23f9d@ramsayjones.plus.com","subject":"Re: [PATCH 1/5] git.txt: HEAD is not that special","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T22:06:22Z","receivedAt":"2023-12-15T22:06:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones writes:\n\n>> -may contain the SHA-1 name of an object or the name of another ref. Refs\n>> -with names beginning `ref/head/` contain the SHA-1 name of the most\n>> +may contain the SHA-1 name of an object or the name of another ref (the\n>> +latter is called a \"symbolic ref\").\n>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most\n>\n> Hmm, s:ref/head:refs/heads: right?\n\nYeah, right, not a new problem with this change, but is indeed a\ngood thing to catch and correct. Thanks for a careful review.\n"},{"id":"485736","messageId":"xmqqttojjegr.fsf@gitster.g","threadId":"60619","inReplyTo":"xmqq1qbnktnl.fsf@gitster.g","subject":"Re: [PATCH 1/5] git.txt: HEAD is not that special","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T22:19:48Z","receivedAt":"2023-12-15T22:19:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Ramsay Jones writes:\n>\n>>> -may contain the SHA-1 name of an object or the name of another ref. Refs\n>>> -with names beginning `ref/head/` contain the SHA-1 name of the most\n>>> +may contain the SHA-1 name of an object or the name of another ref (the\n>>> +latter is called a \"symbolic ref\").\n>>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most\n>>\n>> Hmm, s:ref/head:refs/heads: right?\n>\n> Yeah, right, not a new problem with this change, but is indeed a\n> good thing to catch and correct. Thanks for a careful review.\n\nAnd we have ref/tags/ just below, which I also have fixed locally.\n"},{"id":"485737","messageId":"xmqqjzpfje33.fsf_-_@gitster.g","threadId":"60619","inReplyTo":"xmqqttojjegr.fsf@gitster.g","subject":"[PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-15T22:28:00Z","receivedAt":"2023-12-15T22:28:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"There is no 'ref/notes/' hierarchy. '[format] notes = foo' uses notes\nthat are found in 'refs/notes/foo'.\n\nSigned-off-by: Junio C Hamano \n---\n * According to my eyeballing \"git grep refs/ Documentation\" result,\n this was the only remaining mention of \"ref/\" in Documentation/\n hierarchy that misspells \"refs/\".\n\n Documentation/config/format.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git c/Documentation/config/format.txt w/Documentation/config/format.txt\nindex c98412b697..7410e930e5 100644\n--- c/Documentation/config/format.txt\n+++ w/Documentation/config/format.txt\n@@ -119,7 +119,7 @@ format.notes::\n \t`--notes=`, where `ref` is the non-boolean value. Defaults\n \tto false.\n +\n-If one wishes to use the ref `ref/notes/true`, please use that literal\n+If one wishes to use the ref `refs/notes/true`, please use that literal\n instead.\n +\n This configuration can be specified multiple times in order to allow\n"},{"id":"485738","messageId":"09a519af-43a1-4725-a320-d70f66d66dcf@ramsayjones.plus.com","threadId":"60619","inReplyTo":"xmqqttojjegr.fsf@gitster.g","subject":"Re: [PATCH 1/5] git.txt: HEAD is not that special","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2023-12-15T22:37:41Z","receivedAt":"2023-12-15T22:37:44Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 15/12/2023 22:19, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> \n>> Ramsay Jones writes:\n>>\n>>>> -may contain the SHA-1 name of an object or the name of another ref. Refs\n>>>> -with names beginning `ref/head/` contain the SHA-1 name of the most\n>>>> +may contain the SHA-1 name of an object or the name of another ref (the\n>>>> +latter is called a \"symbolic ref\").\n>>>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most\n>>>\n>>> Hmm, s:ref/head:refs/heads: right?\n>>\n>> Yeah, right, not a new problem with this change, but is indeed a\n>> good thing to catch and correct. Thanks for a careful review.\n> \n> And we have ref/tags/ just below, which I also have fixed locally.\n\nHeh, yeah I missed that, along with 'ref/notes'. ;)\n\nATB,\nRamsay Jones\n\n"},{"id":"485739","messageId":"321b8084-fddb-4b5d-86af-7f88cb3edf7b@ramsayjones.plus.com","threadId":"60619","inReplyTo":"xmqq5y0zkvqx.fsf@gitster.g","subject":"Re: [PATCH 0/5] make room for \"special ref\"","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2023-12-15T22:44:01Z","receivedAt":"2023-12-15T22:44:04Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 15/12/2023 21:21, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> \n>> ... For example, FETCH_HEAD currently stores not\n>> just a single object name, but can and is used to store multiple\n>> object names, each with annotations to record where they came from.\n>> There indeed may be a need to introduce a new term to refer to such\n>> \"special refs\".\n> \n> The \"may be\" here vaguely hints another possibility. If we manage\n> to get rid of the \"special refs\", we do not even have to mention\n> \"special refs\", and more importantly, we do not need extra code to\n> deal with them.\n> \n> For FETCH_HEAD, for example, I wonder if an update along this line\n> is possible:\n> \n> * Teach \"git fetch\" to store what it writes to FETCH_HEAD to a\n> different file, under a distinctly different filename (e.g.,\n> $GIT_DIR/fetched-tips). Demote FETCH_HEAD to a pseudoref, and\n> store the first object name in that \"fetched-tips\" file to it.\n> \n> * Teach \"git pull\" to learn what it used to learn from FETCH_HEAD\n> (i.e., list of fetched tips, each annotated with what ref at what\n> repository it came from and if it is to be merged) from the new\n> \"fetched-tips\" file.\n> \n> The \"special\" ness of FETCH_HEAD is really an implementation detail\n> of how \"git pull\" works and how the findings of \"git fetch\" are\n> communicated to \"git pull\". The general refs API should not have to\n> worry about it, and the refs backends should not have to worry about\n> storing more than just an object name (or if it is a symbolic ref,\n> the target refname).\n> \n> An end-user command like \"git log ORIG_HEAD..FETCH_HEAD\" would not\n> be affected by changes along the above line, because the current\n> FETCH_HEAD, when used as a revision, will work as if it stores the\n> single object name that is listed first in the file.\n> \n> If somebody is reading FETCH_HEAD and acting on its contents (rather\n> than merely consuming it as a ref of the first object), perhaps\n> feeding it to \"git fmt-merge-msg\", they will be broken by such a\n> change (indeed, our own \"git pull\" will be broken by the change to\n> \"git fetch\", and the second bullet point above is about fixing the\n> exact fallout from it), but I am not sure if that is a use case worth\n> worrying about.\n> \n> Hmm?\n> \n\nYes, I was going to suggest exactly this, after Patrick pointed out\nthat there were only two 'special psuedo-refs' (I had a vague feeling\nthere were some more than that) FETCH_HEAD and MERGE_HEAD.\n\nATB,\nRamsay Jones\n\n\n"},{"id":"485740","messageId":"xmqq7clfj7r4.fsf@gitster.g","threadId":"60619","inReplyTo":"321b8084-fddb-4b5d-86af-7f88cb3edf7b@ramsayjones.plus.com","subject":"Re: [PATCH 0/5] make room for \"special ref\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-16T00:44:47Z","receivedAt":"2023-12-16T00:44:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones writes:\n\n> Yes, I was going to suggest exactly this, after Patrick pointed out\n> that there were only two 'special psuedo-refs' (I had a vague feeling\n> there were some more than that) FETCH_HEAD and MERGE_HEAD.\n\nGlad to see that I am not alone. We should be able to treat\nMERGE_HEAD similarly. It is used to communicate the list of \"other\nparents\" from \"git merge\" that stops in the middle (either for merge\nconflict, or in response to the \"--no-commit\" command line option)\nto \"git commit\" that concludes such an unfinished merge. Many\ncommands merely use the presence of MERGE_HEAD as a sign that a\nmerge is in progress (e.g. \"git status\"), which would not break if\nwe just started to record the first parent in a pseudoref MERGE_HEAD\nand wrote the other octopus parents elsewhere, but some commands do\nneed all these parents from MERGE_HEAD (e.g. \"git blame\" that\nsynthesizes a fake starting commit out of the working tree state).\n\nIf we cannot get rid of all \"special refs\" anyway, however, I think\nthere is little that we can gain from doing such \"make FETCH_HEAD\nand MERGE_HEAD into a single-object pseudoref, and write other info\nin separate files\" exercise. We can treat the current FETCH_HEAD\nand MERGE_HEAD as \"file that is not and is more than a ref\", which\nis what the current code is doing anyway, which means we would\ndeclare that they have to stay to be files under $GIT_DIR/ and will\nbe accessed via the filesystem access. At that point, calling them\n\"special ref\" might even be more misleading than its worth and we\nmay be better off to admit that they are not even refs but a\ndatafile some commands can use to obtain input from, but the phrase\nwe use to refer to them, be it \"special ref\" or some random\ndatafile, does not make a fundamental change on anything.\n\n\n"},{"id":"485741","messageId":"1bcd61c3-567f-4b3d-aaee-d29a6091a28d@gmail.com","threadId":"60619","inReplyTo":"20231215203245.3622299-4-gitster@pobox.com","subject":"Re: [PATCH 3/5] refs.h: HEAD is not that special","fromName":"Andy Koppe","fromEmail":"andy.koppe@gmail.com","sentAt":"2023-12-16T10:03:26Z","receivedAt":"2023-12-16T10:03:31Z","isPatch":true,"sender":{"key":"andy.koppe@gmail.com","avatar":"https://avatars.githubusercontent.com/u/223411?v=4"},"body":"On 15/12/2023 20:32, Junio C Hamano wrote:\n> In-code comment explains pseudorefs but used a wrong nomenclature\n> \"special ref\".\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> refs.h | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/refs.h b/refs.h\n> index 23211a5ea1..ff113bb12a 100644\n> --- a/refs.h\n> +++ b/refs.h\n> @@ -56,7 +56,7 @@ struct worktree;\n> * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/\n> * directory and do not consist of all caps and underscores cannot be\n> * resolved. The function returns NULL for such ref names.\n> - * Caps and underscores refers to the special refs, such as HEAD,\n> + * Caps and underscores refers to the pseudorefs, such as HEAD,\n> * FETCH_HEAD and friends, that all live outside of the refs/ directory.\n> */\n> #define RESOLVE_REF_READING 0x01\n\ngitglossary thinks that HEAD is not a pseudoref:\n\n\"Pseudorefs are a class of files under $GIT_DIR which behave like refs \nfor the purposes of rev-parse, but which are treated specially by git. \nPseudorefs both have names that are all-caps, and always start with a \nline consisting of a SHA‐1 followed by whitespace. So, HEAD is not a \npseudoref, because it is sometimes a symbolic ref.\"\n\n(Also, the \"sometimes\" there actually is \"whenever you're on a branch\", \nwhich is most of the time for most people.)\n\nRegards,\nAndy\n"},{"id":"485742","messageId":"132a3daf-23fa-4575-a77f-bdf0a96fb5d8@gmail.com","threadId":"60619","inReplyTo":"321b8084-fddb-4b5d-86af-7f88cb3edf7b@ramsayjones.plus.com","subject":"Re: [PATCH 0/5] make room for \"special ref\"","fromName":"Andy Koppe","fromEmail":"andy.koppe@gmail.com","sentAt":"2023-12-16T10:20:09Z","receivedAt":"2023-12-16T10:20:13Z","isPatch":true,"sender":{"key":"andy.koppe@gmail.com","avatar":"https://avatars.githubusercontent.com/u/223411?v=4"},"body":"On 15/12/2023 22:44, Ramsay Jones wrote:\n> On 15/12/2023 21:21, Junio C Hamano wrote:\n\n>> If somebody is reading FETCH_HEAD and acting on its contents (rather\n>> than merely consuming it as a ref of the first object), perhaps\n>> feeding it to \"git fmt-merge-msg\", they will be broken by such a\n>> change (indeed, our own \"git pull\" will be broken by the change to\n>> \"git fetch\", and the second bullet point above is about fixing the\n>> exact fallout from it), but I am not sure if that is a use case worth\n>> worrying about.\n> \n> Yes, I was going to suggest exactly this, after Patrick pointed out\n> that there were only two 'special psuedo-refs' (I had a vague feeling\n> there were some more than that) FETCH_HEAD and MERGE_HEAD.\n\nAccording to the pseudoref entry of gitglossary, CHERRY_PICK_HEAD also \nstores additional data (which would imply that REVERT_HEAD does too).\nLooking at CHERRY_PICK_HEAD during a pick though, I only see a single \nhash, even when picking multiple commits.\n\nRegards,\nAndy\n"},{"id":"485745","messageId":"ade1666d-9e58-43cb-9e50-8ce04f8d9063@gmail.com","threadId":"60619","inReplyTo":"20231215203245.3622299-1-gitster@pobox.com","subject":"Re: [PATCH 0/5] make room for \"special ref\"","fromName":"Andy Koppe","fromEmail":"andy.koppe@gmail.com","sentAt":"2023-12-16T10:56:15Z","receivedAt":"2023-12-16T10:56:19Z","isPatch":true,"sender":{"key":"andy.koppe@gmail.com","avatar":"https://avatars.githubusercontent.com/u/223411?v=4"},"body":"On 15/12/2023 20:32, Junio C Hamano wrote:\n> A pseudo ref is merely a normal ref with a funny naming convention,\n> i.e., being outside the refs/ hierarchy and has names with all\n> uppercase letters (or an underscore).\n\nI know what you mean, but gitglossary defines pseudorefs as separate \nfrom refs, albeit behaving like refs. Their name itself implies the same.\n\nAlthough the 'ref' entry then goes on to say that \"there are a few \nspecial-purpose refs that do not begin with 'refs/', the most notable \nexample being HEAD.\"\n\nThat implies that at least some of the pseudorefs are refs after all, \nwhile keeping in mind that \"HEAD is not a pseudoref, because it is \nsometimes a symbolic ref\" according to the 'pseudoref' entry.\n\nI think a clearer answer on whether pseudorefs are refs is needed, or at \nleast a better-defined fudge, such as \"pseudorefs are refs except when ...\".\n\nDefining everything under \"refs/\" as refs, and the stuff outside it \nincluding HEAD itself as pseudorefs, would draw clearer lines. The fact \nHEAD is usually symbolic doesn't seem all that relevant from the \nperspective of a user trying to get a grasp of refs and pseudorefs.\n\nRegards,\nAndy\n"},{"id":"485746","messageId":"f03779fa-ddf1-4a3f-b140-55f8bcaeca56@gmail.com","threadId":"60619","inReplyTo":"20231215203245.3622299-6-gitster@pobox.com","subject":"Re: [PATCH 5/5] docs: MERGE_AUTOSTASH is not that special","fromName":"Andy Koppe","fromEmail":"andy.koppe@gmail.com","sentAt":"2023-12-16T11:04:36Z","receivedAt":"2023-12-16T11:04:40Z","isPatch":true,"sender":{"key":"andy.koppe@gmail.com","avatar":"https://avatars.githubusercontent.com/u/223411?v=4"},"body":"On 15/12/2023 20:32, Junio C Hamano wrote:\n> A handful of manual pages called MERGE_AUTOSTASH a \"special ref\",\n> but there is nothing special about it. It merely is yet another\n> pseudoref.\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/merge-options.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt\n> index d8f7cd7ca0..3eaefc4e94 100644\n> --- a/Documentation/merge-options.txt\n> +++ b/Documentation/merge-options.txt\n> @@ -191,7 +191,7 @@ endif::git-pull[]\n> --autostash::\n> --no-autostash::\n> \tAutomatically create a temporary stash entry before the operation\n> -\tbegins, record it in the special ref `MERGE_AUTOSTASH`\n> +\tbegins, record it in the ref `MERGE_AUTOSTASH`\n> \tand apply it after the operation ends. This means\n> \tthat you can run the operation on a dirty worktree. However, use\n> \twith care: the final stash application after a successful\n\nShould that say 'pseudoref' instead of 'ref'?\n\nAnd since MERGE_AUTOSTASH is documented here, it probably should be in \ngitrevisions as well.\n\nRegards,\nAndy\n"},{"id":"485765","messageId":"ZX_9nRYKVq0jT0Lp@tanuki","threadId":"60619","inReplyTo":"xmqqjzpfje33.fsf_-_@gitster.g","subject":"Re: [PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2023-12-18T08:06:53Z","receivedAt":"2023-12-18T08:06:58Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Dec 15, 2023 at 02:28:00PM -0800, Junio C Hamano wrote:\n> There is no 'ref/notes/' hierarchy. '[format] notes = foo' uses notes\n> that are found in 'refs/notes/foo'.\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> * According to my eyeballing \"git grep refs/ Documentation\" result,\n> this was the only remaining mention of \"ref/\" in Documentation/\n> hierarchy that misspells \"refs/\".\n\nThis made me look for additional instances where we were referring to\n\"ref/\". Turns out it's only a very limited set, see the below diff. Take\nthe translation changes with a big grain of salt though, and neither am\nI sure whether we want to fix up past release notes. Also, the test is\ninteresting because it would fail even if we didn't pass an invalid atom\nto git-for-each-ref(1).\n\nAnyway, the patch you have looks obviously correct to me. I would be\nhappy to turn the below diff into a proper patch, but also wouldn't mind\nto let you roll them into your patch series. Please let me know your\npreference.\n\nPatrick\n\ndiff --git a/Documentation/RelNotes/2.1.1.txt b/Documentation/RelNotes/2.1.1.txt\nindex 830fc3cc6d..d46e142119 100644\n--- a/Documentation/RelNotes/2.1.1.txt\n+++ b/Documentation/RelNotes/2.1.1.txt\n@@ -29,7 +29,7 @@ Git v2.1.1 Release Notes\n * \"git add x\" where x that used to be a directory has become a\n symbolic link to a directory misbehaved.\n \n- * The prompt script checked $GIT_DIR/ref/stash file to see if there\n+ * The prompt script checked $GIT_DIR/refs/stash file to see if there\n is a stash, which was a no-no.\n \n * \"git checkout -m\" did not switch to another branch while carrying\ndiff --git a/Documentation/RelNotes/2.2.0.txt b/Documentation/RelNotes/2.2.0.txt\nindex e98ecbcff6..806908ddb2 100644\n--- a/Documentation/RelNotes/2.2.0.txt\n+++ b/Documentation/RelNotes/2.2.0.txt\n@@ -205,7 +205,7 @@ notes for details).\n * \"git add x\" where x used to be a directory and is now a\n symbolic link to a directory misbehaved.\n \n- * The prompt script checked the $GIT_DIR/ref/stash file to see if there\n+ * The prompt script checked the $GIT_DIR/refs/stash file to see if there\n is a stash, which was a no-no.\n \n * Pack-protocol documentation had a minor typo.\ndiff --git a/po/fr.po b/po/fr.po\nindex ee2e610ef1..744550b056 100644\n--- a/po/fr.po\n+++ b/po/fr.po\n@@ -19773,7 +19773,7 @@ msgid \"\"\n \"Neither worked, so we gave up. You must fully qualify the ref.\"\n msgstr \"\"\n \"La destination que vous avez fournie n'est pas un nom de référence complète\\n\"\n-\"(c'est-à-dire commençant par \\\"ref/\\\"). Essai d'approximation par :\\n\"\n+\"(c'est-à-dire commençant par \\\"refs/\\\"). Essai d'approximation par :\\n\"\n \"\\n\"\n \"- Recherche d'une référence qui correspond à '%s' sur le serveur distant.\\n\"\n \"- Vérification si la en cours de poussée ('%s')\\n\"\ndiff --git a/po/zh_CN.po b/po/zh_CN.po\nindex 86402725b2..eb47e8f9b7 100644\n--- a/po/zh_CN.po\n+++ b/po/zh_CN.po\n@@ -13224,8 +13224,8 @@ msgid \"\"\n msgid_plural \"\"\n \"Note: Some branches outside the refs/remotes/ hierarchy were not removed;\\n\"\n \"to delete them, use:\"\n-msgstr[0] \"注意：ref/remotes 层级之外的一个分支未被移除。要删除它，使用：\"\n-msgstr[1] \"注意：ref/remotes 层级之外的一些分支未被移除。要删除它们，使用：\"\n+msgstr[0] \"注意：refs/remotes 层级之外的一个分支未被移除。要删除它，使用：\"\n+msgstr[1] \"注意：refs/remotes 层级之外的一些分支未被移除。要删除它们，使用：\"\n \n #: builtin/remote.c\n #, c-format\ndiff --git a/po/zh_TW.po b/po/zh_TW.po\nindex f777a0596f..b2a79cdd93 100644\n--- a/po/zh_TW.po\n+++ b/po/zh_TW.po\n@@ -13109,7 +13109,7 @@ msgid \"\"\n msgid_plural \"\"\n \"Note: Some branches outside the refs/remotes/ hierarchy were not removed;\\n\"\n \"to delete them, use:\"\n-msgstr[0] \"注意：ref/remotes 層級之外的一個分支未被移除。要刪除它，使用：\"\n+msgstr[0] \"注意：refs/remotes 層級之外的一個分支未被移除。要刪除它，使用：\"\n \n #: builtin/remote.c\n #, c-format\ndiff --git a/t/t6300-for-each-ref.sh b/t/t6300-for-each-ref.sh\nindex 54e2281259..e68f7bec8e 100755\n--- a/t/t6300-for-each-ref.sh\n+++ b/t/t6300-for-each-ref.sh\n@@ -841,7 +841,7 @@ test_expect_success 'err on bad describe atom arg' '\n \t\tEOF\n \t\ttest_must_fail git for-each-ref \\\n \t\t\t--format=\"%(describe:tags,qux=1,abbrev=14)\" \\\n-\t\t\tref/heads/master 2>actual &&\n+\t\t\trefs/heads/master 2>actual &&\n \t\ttest_cmp expect actual\n \t)\n '\n\n"},{"id":"485767","messageId":"ZYABwulbgbAwDewD@tanuki","threadId":"60619","inReplyTo":"132a3daf-23fa-4575-a77f-bdf0a96fb5d8@gmail.com","subject":"Re: [PATCH 0/5] make room for \"special ref\"","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2023-12-18T08:24:34Z","receivedAt":"2023-12-18T08:24:39Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sat, Dec 16, 2023 at 10:20:09AM +0000, Andy Koppe wrote:\n> On 15/12/2023 22:44, Ramsay Jones wrote:\n> > On 15/12/2023 21:21, Junio C Hamano wrote:\n> \n> > > If somebody is reading FETCH_HEAD and acting on its contents (rather\n> > > than merely consuming it as a ref of the first object), perhaps\n> > > feeding it to \"git fmt-merge-msg\", they will be broken by such a\n> > > change (indeed, our own \"git pull\" will be broken by the change to\n> > > \"git fetch\", and the second bullet point above is about fixing the\n> > > exact fallout from it), but I am not sure if that is a use case worth\n> > > worrying about.\n> > \n> > Yes, I was going to suggest exactly this, after Patrick pointed out\n> > that there were only two 'special psuedo-refs' (I had a vague feeling\n> > there were some more than that) FETCH_HEAD and MERGE_HEAD.\n> \n> According to the pseudoref entry of gitglossary, CHERRY_PICK_HEAD also\n> stores additional data (which would imply that REVERT_HEAD does too).\n> Looking at CHERRY_PICK_HEAD during a pick though, I only see a single hash,\n> even when picking multiple commits.\n\nBoth CHERRY_PICK_HEAD and REVERT_HEAD are only ever updated via the refs\nAPI, so neither of them ever contains anything other than a normal ref.\nI guess we should update the glossary accordingly.\n\nPatrick\n"},{"id":"485768","messageId":"ZYAFx9gfppkS2Oey@tanuki","threadId":"60619","inReplyTo":"xmqq7clfj7r4.fsf@gitster.g","subject":"Re: [PATCH 0/5] make room for \"special ref\"","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2023-12-18T08:41:43Z","receivedAt":"2023-12-18T08:41:48Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Dec 15, 2023 at 04:44:47PM -0800, Junio C Hamano wrote:\n> Ramsay Jones writes:\n> \n> > Yes, I was going to suggest exactly this, after Patrick pointed out\n> > that there were only two 'special psuedo-refs' (I had a vague feeling\n> > there were some more than that) FETCH_HEAD and MERGE_HEAD.\n\nI don't think there are more special refs than those two. Andy pointed\nout CHERRY_PICK_HEAD and REVERT_HEAD, but both of them actually get\naccessed via the ref backend exclusively and thus cannot be special in\nany way. Also, the test suite of Git passes with only those two refs\nmarked as special refs with the reftable backend, which is another good\nindicator that I didn't miss anything here because we definitely can't\nstore special information in the reftable backend.\n\nIt's of course still possible that our test suite has a blind spot and\nthat I missed any special refs. If so, I would love to hear about them.\n\n> Glad to see that I am not alone. We should be able to treat\n> MERGE_HEAD similarly. It is used to communicate the list of \"other\n> parents\" from \"git merge\" that stops in the middle (either for merge\n> conflict, or in response to the \"--no-commit\" command line option)\n> to \"git commit\" that concludes such an unfinished merge. Many\n> commands merely use the presence of MERGE_HEAD as a sign that a\n> merge is in progress (e.g. \"git status\"), which would not break if\n> we just started to record the first parent in a pseudoref MERGE_HEAD\n> and wrote the other octopus parents elsewhere, but some commands do\n> need all these parents from MERGE_HEAD (e.g. \"git blame\" that\n> synthesizes a fake starting commit out of the working tree state).\n\nI would certainly love to drop the \"specialness\" of both FETCH_HEAD and\nMERGE_HEAD, but I am a bit pessimistic about whether we really can. The\nformat of those refs has been around for quite a long time already, and\nI do expect that there is tooling out there that parses those files.\n\nI would claim that it's especially likely that FETCH_HEAD is getting\nparsed by external tools. Historically, there has not been a way to\nreally figure out which refs have been updated in git-fetch(1). So any\nscripts that perform a fetch and want to learn about what was updated\nwould very likely resort to parsing FETCH_HEAD. This has changed a bit\nwith the introduction of the machine-parsable interface of git-fetch(1),\nbut it has only been introduced rather recently with Git v2.42.\n\n> If we cannot get rid of all \"special refs\" anyway, however, I think\n> there is little that we can gain from doing such \"make FETCH_HEAD\n> and MERGE_HEAD into a single-object pseudoref, and write other info\n> in separate files\" exercise. We can treat the current FETCH_HEAD\n> and MERGE_HEAD as \"file that is not and is more than a ref\", which\n> is what the current code is doing anyway, which means we would\n> declare that they have to stay to be files under $GIT_DIR/ and will\n> be accessed via the filesystem access.\n\nI'd like for it to be otherwise, but I think this is the only sensible\nthing to do. I think it was a mistake to introduce those special refs\nlike this and treat them almost like a real ref, but that's always easy\nto say in hindsight.\n\n> At that point, calling them \"special ref\" might even be more\n> misleading than its worth and we may be better off to admit that they\n> are not even refs but a datafile some commands can use to obtain input\n> from, but the phrase we use to refer to them, be it \"special ref\" or\n> some random datafile, does not make a fundamental change on anything.\n\nWell, the problem is that these do indeed behave like a ref for most of\nthe part: you can ask for them via git-rev-parse(1) and we'll resolve\nthem just fine, even though we only ever return the first object ID. So\neven though I'm not a huge fan of calling them \"special ref\", I think we\nshould at least highlight the reflike-nature in whatever we want to call\nthem.\n\nPatrick\n"},{"id":"485769","messageId":"ZYAGyLH4nm4TebA_@tanuki","threadId":"60619","inReplyTo":"20231215203245.3622299-2-gitster@pobox.com","subject":"Re: [PATCH 1/5] git.txt: HEAD is not that special","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2023-12-18T08:46:00Z","receivedAt":"2023-12-18T08:46:04Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Dec 15, 2023 at 12:32:41PM -0800, Junio C Hamano wrote:\n> The introductory text in \"git help git\" that describes HEAD called\n> it \"a special ref\". It is special compared to the more regular refs\n> like refs/heads/master and refs/tags/v1.0.0, but not that special,\n> unlike truly special ones like FETCH_HEAD.\n> \n> Rewrite a few sentences to also introduce the distinction between a\n> regular ref that contain the object name and a symbolic ref that\n> contain the name of another ref. Update the description of HEAD\n> that point at the current branch to use the more correct term, a\n> \"symbolic ref\".\n> \n> This was found as part of auditing the documentation and in-code\n> comments for uses of \"special ref\" that refer merely a \"pseudo ref\".\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git.txt | 7 ++++---\n> 1 file changed, 4 insertions(+), 3 deletions(-)\n> \n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index 2535a30194..880cdc5d7f 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for\n> efficiency may later be compressed together into \"pack files\".\n> \n> Named pointers called refs mark interesting points in history. A ref\n> -may contain the SHA-1 name of an object or the name of another ref. Refs\n> -with names beginning `ref/head/` contain the SHA-1 name of the most\n> +may contain the SHA-1 name of an object or the name of another ref (the\n> +latter is called a \"symbolic ref\").\n\nOn a tangent: While we have a name for symbolic refs, do we also have a\nname for non-symbolic refs? I often use the term \"direct ref\" to clearly\ndistinguish them from symbolic refs, but it's of course not defined in\nour glossary.\n\n> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most\n> recent commit (or \"head\") of a branch under development. SHA-1 names of\n> -tags of interest are stored under `ref/tags/`. A special ref named\n> +tags of interest are stored under `ref/tags/`. A symbolic ref named\n> `HEAD` contains the name of the currently checked-out branch.\n\nI was briefly wondering whether we also want to replace SHA-1 with\n\"object hash\" while at it, but it's certainly out of the scope of this\npatch series.\n\nPatrick\n"},{"id":"485770","messageId":"ZYAJJzUtpBkhVEbG@tanuki","threadId":"60619","inReplyTo":"20231215203245.3622299-1-gitster@pobox.com","subject":"Re: [PATCH 0/5] make room for \"special ref\"","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2023-12-18T08:56:07Z","receivedAt":"2023-12-18T08:56:15Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Dec 15, 2023 at 12:32:40PM -0800, Junio C Hamano wrote:\n> Patrick's reftable work is progressing nicely and wants to establish\n> \"special ref\" as a phrase with some defined meaning that is somewhat\n> different from a mere \"pseudo ref\".\n> \n> A pseudo ref is merely a normal ref with a funny naming convention,\n> i.e., being outside the refs/ hierarchy and has names with all\n> uppercase letters (or an underscore). But there truly are refs that\n> are more than that. For example, FETCH_HEAD currently stores not\n> just a single object name, but can and is used to store multiple\n> object names, each with annotations to record where they came from.\n> There indeed may be a need to introduce a new term to refer to such\n> \"special refs\".\n> \n> Existing documentation, however, uses \"special ref\" to refer to\n> pseudo refs without any \"special\" property, like FETCH_HEAD does.\n> \n> This series merely corrects such existing uses of the word, to make\n> room for Patrick's series to introduce (and formally define in the\n> glossary) \"special refs\".\n\nThanks for helping out with this effort and kicking off the discussion,\nI highly appreciate it!\n\nPatrick\n\n> Junio C Hamano (5):\n> git.txt: HEAD is not that special\n> git-bisect.txt: BISECT_HEAD is not that special\n> refs.h: HEAD is not that special\n> docs: AUTO_MERGE is not that special\n> docs: MERGE_AUTOSTASH is not that special\n> \n> Documentation/git-bisect.txt | 2 +-\n> Documentation/git-diff.txt | 2 +-\n> Documentation/git-merge.txt | 2 +-\n> Documentation/git.txt | 7 ++++---\n> Documentation/merge-options.txt | 2 +-\n> Documentation/user-manual.txt | 2 +-\n> refs.h | 2 +-\n> 7 files changed, 10 insertions(+), 9 deletions(-)\n> \n> -- \n> 2.43.0-76-g1a87c842ec\n> \n"},{"id":"485779","messageId":"xmqq1qbjij0f.fsf@gitster.g","threadId":"60619","inReplyTo":"ZX_9nRYKVq0jT0Lp@tanuki","subject":"Re: [PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-18T16:16:00Z","receivedAt":"2023-12-18T16:16:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Fri, Dec 15, 2023 at 02:28:00PM -0800, Junio C Hamano wrote:\n>> There is no 'ref/notes/' hierarchy. '[format] notes = foo' uses notes\n>> that are found in 'refs/notes/foo'.\n>> \n>> Signed-off-by: Junio C Hamano \n>> ---\n>> * According to my eyeballing \"git grep refs/ Documentation\" result,\n>> this was the only remaining mention of \"ref/\" in Documentation/\n>> hierarchy that misspells \"refs/\".\n>\n> This made me look for additional instances where we were referring to\n> \"ref/\". Turns out it's only a very limited set, see the below diff.\n\nYup, I did the same grep, but I tend to avoid churning what we\npublished long ago (and kept in Documentation/RelNotes/), my patches\nonly covered documents that are still relevant.\n\n> the translation changes with a big grain of salt though,\n\nHopefully pinging Jiang would be sufficient to ask help from the\nFrench, Chinese, and Taiwaneese translation teams.\n\n> diff --git a/po/fr.po b/po/fr.po\n> index ee2e610ef1..744550b056 100644\n> --- a/po/fr.po\n> +++ b/po/fr.po\n> @@ -19773,7 +19773,7 @@ msgid \"\"\n> \"Neither worked, so we gave up. You must fully qualify the ref.\"\n> msgstr \"\"\n> \"La destination que vous avez fournie n'est pas un nom de référence complète\\n\"\n> -\"(c'est-à-dire commençant par \\\"ref/\\\"). Essai d'approximation par :\\n\"\n> +\"(c'est-à-dire commençant par \\\"refs/\\\"). Essai d'approximation par :\\n\"\n> \"\\n\"\n> \"- Recherche d'une référence qui correspond à '%s' sur le serveur distant.\\n\"\n> \"- Vérification si la en cours de poussée ('%s')\\n\"\n> diff --git a/po/zh_CN.po b/po/zh_CN.po\n> index 86402725b2..eb47e8f9b7 100644\n> --- a/po/zh_CN.po\n> +++ b/po/zh_CN.po\n> @@ -13224,8 +13224,8 @@ msgid \"\"\n> msgid_plural \"\"\n> \"Note: Some branches outside the refs/remotes/ hierarchy were not removed;\\n\"\n> \"to delete them, use:\"\n> -msgstr[0] \"注意：ref/remotes 层级之外的一个分支未被移除。要删除它，使用：\"\n> -msgstr[1] \"注意：ref/remotes 层级之外的一些分支未被移除。要删除它们，使用：\"\n> +msgstr[0] \"注意：refs/remotes 层级之外的一个分支未被移除。要删除它，使用：\"\n> +msgstr[1] \"注意：refs/remotes 层级之外的一些分支未被移除。要删除它们，使用：\"\n> \n> #: builtin/remote.c\n> #, c-format\n> diff --git a/po/zh_TW.po b/po/zh_TW.po\n> index f777a0596f..b2a79cdd93 100644\n> --- a/po/zh_TW.po\n> +++ b/po/zh_TW.po\n> @@ -13109,7 +13109,7 @@ msgid \"\"\n> msgid_plural \"\"\n> \"Note: Some branches outside the refs/remotes/ hierarchy were not removed;\\n\"\n> \"to delete them, use:\"\n> -msgstr[0] \"注意：ref/remotes 層級之外的一個分支未被移除。要刪除它，使用：\"\n> +msgstr[0] \"注意：refs/remotes 層級之外的一個分支未被移除。要刪除它，使用：\"\n> \n> #: builtin/remote.c\n> #, c-format\n\n> Also, the test is\n> interesting because it would fail even if we didn't pass an invalid atom\n> to git-for-each-ref(1).\n\nIt is interesting but not surprising. It is not an error to use ref\npatterns that do not match any ref. It is a mere pattern to filtering\nwhat are in refs/ for the ones to be output.\n\n> diff --git a/t/t6300-for-each-ref.sh b/t/t6300-for-each-ref.sh\n> index 54e2281259..e68f7bec8e 100755\n> --- a/t/t6300-for-each-ref.sh\n> +++ b/t/t6300-for-each-ref.sh\n> @@ -841,7 +841,7 @@ test_expect_success 'err on bad describe atom arg' '\n> \t\tEOF\n> \t\ttest_must_fail git for-each-ref \\\n> \t\t\t--format=\"%(describe:tags,qux=1,abbrev=14)\" \\\n> -\t\t\tref/heads/master 2>actual &&\n> +\t\t\trefs/heads/master 2>actual &&\n> \t\ttest_cmp expect actual\n> \t)\n> '\n\nThe \"for-each-ref\" family's \"--format\" string is first parsed and\nsanity-checked before it is applied. The bogus ref pattern may not\nyield any ref to apply the format string, but we do not optimize out\nthe parsing and checking, even though we could, as it would be\noptimizing for a wrong case. So regardless of the ref pattern at\nthe end of the command line does not make a difference to the\noutcome of this test.\n"},{"id":"485782","messageId":"xmqqplz3h3y7.fsf@gitster.g","threadId":"60619","inReplyTo":"ZYAGyLH4nm4TebA_@tanuki","subject":"Re: [PATCH 1/5] git.txt: HEAD is not that special","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-18T16:26:40Z","receivedAt":"2023-12-18T16:26:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n>> Named pointers called refs mark interesting points in history. A ref\n>> -may contain the SHA-1 name of an object or the name of another ref. Refs\n>> -with names beginning `ref/head/` contain the SHA-1 name of the most\n>> +may contain the SHA-1 name of an object or the name of another ref (the\n>> +latter is called a \"symbolic ref\").\n>\n> On a tangent: While we have a name for symbolic refs, do we also have a\n> name for non-symbolic refs? I often use the term \"direct ref\" to clearly\n> distinguish them from symbolic refs, but it's of course not defined in\n> our glossary.\n\nYou may find me saying \"normal ref\", \"regular ref\", or somesuch when\nit is not clear from the context if you dig the list archive.\n\"direct\" is a nice word, especially it would give us a good pair of\nterms if we are to change \"symbolic\" to \"indirect\", but since we are\nnot going to do so, I am not sure the contrast between \"direct\" and\n\"symbolic\" would make such a good pair.\n\nBut quite honestly I rarely felt a need for a specific term, as it\nis fairly clear from the context, e.g.\n\n * \"From a ref, we locate an object using the object name it\n records and use the object\"\n\n A statement written from the point of view of the consumer of\n object name, it does not matter if the object name is directly\n found in the ref, or indirection is involved to find such a\n concrete ref that records an object name by following the\n original symbolic ref.\n\n * \"A ref usually stores an object name, but it can also be a\n symbolic ref that points at another ref, in which case, asking\n what object such a symbolic ref points at would yield the object\n the other ref points at\".\n\nSo I dunno.\n\n>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most\n>> recent commit (or \"head\") of a branch under development. SHA-1 names of\n>> -tags of interest are stored under `ref/tags/`. A special ref named\n>> +tags of interest are stored under `ref/tags/`. A symbolic ref named\n>> `HEAD` contains the name of the currently checked-out branch.\n>\n> I was briefly wondering whether we also want to replace SHA-1 with\n> \"object hash\" while at it, but it's certainly out of the scope of this\n> patch series.\n\nYup, there still are too many reference to SHA-1 (and \"sha1\", which\nis even worse), and it is not a focus of this series.\n\nThanks.\n"},{"id":"485815","messageId":"CANYiYbHFA+1R1JdN-o6TAJqDbh7iSmELjpc2kK8HkHJ7RQLgGA@mail.gmail.com","threadId":"60619","inReplyTo":"xmqq1qbjij0f.fsf@gitster.g","subject":"Re: [PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy","fromName":"Jiang Xin","fromEmail":"worldhello.net@gmail.com","sentAt":"2023-12-19T15:33:03Z","receivedAt":"2023-12-19T15:33:15Z","isPatch":true,"sender":{"key":"worldhello.net@gmail.com","avatar":"https://avatars.githubusercontent.com/u/183860?v=4"},"body":"On Tue, Dec 19, 2023 at 12:16 AM Junio C Hamano wrote:\n>\n> Patrick Steinhardt writes:\n> > the translation changes with a big grain of salt though,\n>\n> Hopefully pinging Jiang would be sufficient to ask help from the\n> French, Chinese, and Taiwaneese translation teams.\n\nThe l10n team has a command line tool called git-po-helper that can\ncheck for spelling errors in translations, such as mismatched command\nnames, configuration variables. A new pattern will be added to find\nmismatched reference prefixes, and the following typos will be fixed\nduring the next localization window.\n\n> > diff --git a/po/fr.po b/po/fr.po\n> > index ee2e610ef1..744550b056 100644\n> > --- a/po/fr.po\n> > +++ b/po/fr.po\n> > @@ -19773,7 +19773,7 @@ msgid \"\"\n> > \"Neither worked, so we gave up. You must fully qualify the ref.\"\n> > msgstr \"\"\n> > \"La destination que vous avez fournie n'est pas un nom de référence complète\\n\"\n> > -\"(c'est-à-dire commençant par \\\"ref/\\\"). Essai d'approximation par :\\n\"\n> > +\"(c'est-à-dire commençant par \\\"refs/\\\"). Essai d'approximation par :\\n\"\n> > \"\\n\"\n> > \"- Recherche d'une référence qui correspond à '%s' sur le serveur distant.\\n\"\n> > \"- Vérification si la en cours de poussée ('%s')\\n\"\n> > diff --git a/po/zh_CN.po b/po/zh_CN.po\n> > index 86402725b2..eb47e8f9b7 100644\n> > --- a/po/zh_CN.po\n> > +++ b/po/zh_CN.po\n> > @@ -13224,8 +13224,8 @@ msgid \"\"\n> > msgid_plural \"\"\n> > \"Note: Some branches outside the refs/remotes/ hierarchy were not removed;\\n\"\n> > \"to delete them, use:\"\n> > -msgstr[0] \"注意：ref/remotes 层级之外的一个分支未被移除。要删除它，使用：\"\n> > -msgstr[1] \"注意：ref/remotes 层级之外的一些分支未被移除。要删除它们，使用：\"\n> > +msgstr[0] \"注意：refs/remotes 层级之外的一个分支未被移除。要删除它，使用：\"\n> > +msgstr[1] \"注意：refs/remotes 层级之外的一些分支未被移除。要删除它们，使用：\"\n> >\n> > #: builtin/remote.c\n> > #, c-format\n> > diff --git a/po/zh_TW.po b/po/zh_TW.po\n> > index f777a0596f..b2a79cdd93 100644\n> > --- a/po/zh_TW.po\n> > +++ b/po/zh_TW.po\n> > @@ -13109,7 +13109,7 @@ msgid \"\"\n> > msgid_plural \"\"\n> > \"Note: Some branches outside the refs/remotes/ hierarchy were not removed;\\n\"\n> > \"to delete them, use:\"\n> > -msgstr[0] \"注意：ref/remotes 層級之外的一個分支未被移除。要刪除它，使用：\"\n> > +msgstr[0] \"注意：refs/remotes 層級之外的一個分支未被移除。要刪除它，使用：\"\n> >\n> > #: builtin/remote.c\n> > #, c-format\n"}]}