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@xxxxxxxxx> > --- > 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:
signature.asc
Description: PGP signature
