| Message ID | 9659d7da3f38e706af22b4cef0a3e77f780493fd.1714479928.git.ps@pks.im (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Clarify pseudo-ref terminology | expand |
Patrick Steinhardt <ps@pks.im> writes: > Except for the pseudorefs MERGE_HEAD and FETCH_HEAD, all refs that live > in the root of the ref hierarchy behave the exact same as normal refs. > They can be symbolic refs or direct refs and can be read, iterated over > and written via normal tooling. All of these refs are stored in the ref > backends, which further demonstrates that they are just normal refs. > > Extend the definition of "ref" to also cover such root refs. The only > additional restriction for root refs is that they must conform to a > specific naming schema. > > Signed-off-by: Patrick Steinhardt <ps@pks.im> > --- > Documentation/glossary-content.txt | 33 +++++++++++++++++++++++------- > 1 file changed, 26 insertions(+), 7 deletions(-) > > diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt > index 13e1aa63ab..683b727349 100644 > --- a/Documentation/glossary-content.txt > +++ b/Documentation/glossary-content.txt > @@ -550,20 +550,39 @@ The following pseudorefs are known to Git: > to the result. > > [[def_ref]]ref:: > - A name that begins with `refs/` (e.g. `refs/heads/master`) > - that points to an <<def_object_name,object name>> or another > - ref (the latter is called a <<def_symref,symbolic ref>>). > + A name that that points to an <<def_object_name,object name>> or > + another ref (the latter is called a <<def_symref,symbolic ref>>). > For convenience, a ref can sometimes be abbreviated when used > as an argument to a Git command; see linkgit:gitrevisions[7] > for details. > Refs are stored in the <<def_repository,repository>>. > + > The ref namespace is hierarchical. > -Different subhierarchies are used for different purposes (e.g. the > -`refs/heads/` hierarchy is used to represent local branches). > +Ref names must either start with `refs/` or be located in the root of > +the hierarchy. In that case, their name must conform to the following > +rules: > + The last sentence here doesn't clarify what it is referring to, perhaps something like 'For the latter, their name must follow these rules:' instead? > -There are a few special-purpose refs that do not begin with `refs/`. > -The most notable example is `HEAD`. > + - The name consists of only upper-case characters or underscores. > + > + - The name ends with "`_HEAD`" or is equal to "`HEAD`". > ++ > +There are some irregular refs in the root of the hierarchy that do not > +match these rules. The following list is exhaustive and shall not be > +extended in the future: > ++ > + - AUTO_MERGE > + > + - BISECT_EXPECTED_REV > + > + - NOTES_MERGE_PARTIAL > + > + - NOTES_MERGE_REF > + > + - MERGE_AUTOSTASH > ++ > +Different subhierarchies are used for different purposes. For example, > +the `refs/heads/` hierarchy is used to represent local branches whereas > +the `refs/tags/` hierarchy is used to represent local tags.. > > [[def_reflog]]reflog:: > A reflog shows the local "history" of a ref. In other words, > -- > 2.45.0
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 13e1aa63ab..683b727349 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -550,20 +550,39 @@ The following pseudorefs are known to Git: to the result. [[def_ref]]ref:: - A name that begins with `refs/` (e.g. `refs/heads/master`) - that points to an <<def_object_name,object name>> or another - ref (the latter is called a <<def_symref,symbolic ref>>). + A name that that points to an <<def_object_name,object name>> or + another ref (the latter is called a <<def_symref,symbolic ref>>). For convenience, a ref can sometimes be abbreviated when used as an argument to a Git command; see linkgit:gitrevisions[7] for details. Refs are stored in the <<def_repository,repository>>. + The ref namespace is hierarchical. -Different subhierarchies are used for different purposes (e.g. the -`refs/heads/` hierarchy is used to represent local branches). +Ref names must either start with `refs/` or be located in the root of +the hierarchy. In that case, their name must conform to the following +rules: + -There are a few special-purpose refs that do not begin with `refs/`. -The most notable example is `HEAD`. + - The name consists of only upper-case characters or underscores. + + - The name ends with "`_HEAD`" or is equal to "`HEAD`". ++ +There are some irregular refs in the root of the hierarchy that do not +match these rules. The following list is exhaustive and shall not be +extended in the future: ++ + - AUTO_MERGE + + - BISECT_EXPECTED_REV + + - NOTES_MERGE_PARTIAL + + - NOTES_MERGE_REF + + - MERGE_AUTOSTASH ++ +Different subhierarchies are used for different purposes. For example, +the `refs/heads/` hierarchy is used to represent local branches whereas +the `refs/tags/` hierarchy is used to represent local tags.. [[def_reflog]]reflog:: A reflog shows the local "history" of a ref. In other words,
Except for the pseudorefs MERGE_HEAD and FETCH_HEAD, all refs that live in the root of the ref hierarchy behave the exact same as normal refs. They can be symbolic refs or direct refs and can be read, iterated over and written via normal tooling. All of these refs are stored in the ref backends, which further demonstrates that they are just normal refs. Extend the definition of "ref" to also cover such root refs. The only additional restriction for root refs is that they must conform to a specific naming schema. Signed-off-by: Patrick Steinhardt <ps@pks.im> --- Documentation/glossary-content.txt | 33 +++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-)