| Message ID | 20231215203245.3622299-2-gitster@pobox.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | make room for "special ref" | expand |
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
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.
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.
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
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
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.
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
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(-)