Re: [PATCH v2 03/10] Documentation/glossary: define root refs as refs

Karthik Nayak
2024-04-30T12:56:19Z

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

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

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