Re: [PATCH v2 01/10] Documentation/glossary: redefine pseudorefs as special refs
Patrick Steinhardt <ps@pks.im> writes:
Show 12 quoted lines
> Nowadays, Git knows about three different kinds of refs. As defined in
> gitglossary(7):
>
> - Regular refs that start with "refs/", like "refs/heads/main".
>
> - Pseudorefs, which live in the root directory. These must have
> all-caps names and must be a file that start with an object hash.
> Consequently, symbolic refs are not pseudorefs because they do not
> start with an object hash.
>
> - Special refs, of which we only have "FETCH_HEAD" and "MERGE_HEAD".
>
Nit: but since you go into explaining what the _old_ pseudoref is,
perhaps you should also add a line about why "FETCH_HEAD" and
"MERGE_HEAD" were called special refs.
Show 24 quoted lines
> This state is extremely confusing, and I would claim that most folks
> don't fully understand what is what here. The current definitions also
> have several problems:
>
> - Where does "HEAD" fit in? It's not a pseudoref because it can be
> a symbolic ref. It's not a regular ref because it does not start
> with "refs/". And it's not a special ref, either.
>
> - There is a strong overlap between pseudorefs and special refs. The
> pseudoref section for example mentions "MERGE_HEAD", even though it
> is a special ref. Is it thus both a pseudoref and a special ref?
>
> - Why do we even need to distinguish refs that live in the root from
> other refs when they behave just like a regular ref anyway?
>
> In other words, the current state is quite a mess and leads to wild
> inconsistencies without much of a good reason.
>
> The original reason why pseudorefs were introduced is that there are
> some refs that sometimes behave like a ref, even though they aren't a
> ref. And we really only have two of these nowadads, namely "MERGE_HEAD"
> and "FETCH_HEAD". Those files are never written via the ref backends,
> but are instead written by git-fetch(1), git-pull(1) and git-merge(1).
> They contain additional metadata that hihlights where a ref has been
> fetched from or the list of commits that have been merged.
This is good detail and I guess you can skip my earlier suggestion.
Show 47 quoted lines
> This original intent in fact matches the definition of special refs that
> we have recently introduced in 8df4c5d205 (Documentation: add "special
> refs" to the glossary, 2024-01-19). Due to the introduction of the new
> reftable backend we were forced to distinguish those refs more clearly
> such that we don't ever try to read or write them via the reftable
> backend. In the same series, we also addressed all the other cases where
> we used to write those special refs via the filesystem directly, thus
> circumventing the ref backend, to instead write them via the backends.
> Consequently, there are no other refs left anymore which are special.
>
> Let's address this mess and return the pseudoref terminology back to its
> original intent: a ref that sometimes behave like a ref, but which isn't
> really a ref because it gets written to the filesystem directly. Or in
> other words, let's redefine pseudorefs to match the current definition
> of special refs. As special refs and pseudorefs are now the same per
> definition, we can drop the "special refs" term again. It's not exposed
> to our users and thus they wouldn't ever encounter that term anyway.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> Documentation/glossary-content.txt | 42 +++++++++---------------------
> 1 file changed, 13 insertions(+), 29 deletions(-)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index d71b199955..f5c0f49150 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -496,21 +496,19 @@ exclude;;
> that start with `refs/bisect/`, but might later include other
> unusual refs.
>
> -[[def_pseudoref]]pseudoref::
> - Pseudorefs are a class of files under `$GIT_DIR` which behave
> - like refs for the purposes of rev-parse, but which are treated
> - specially by git. Pseudorefs both have names that are all-caps,
> - and always start with a line consisting of a
> - <<def_SHA1,SHA-1>> followed by whitespace. So, HEAD is not a
> - pseudoref, because it is sometimes a symbolic ref. They might
> - optionally contain some additional data. `MERGE_HEAD` and
> - `CHERRY_PICK_HEAD` are examples. Unlike
> - <<def_per_worktree_ref,per-worktree refs>>, these files cannot
> - be symbolic refs, and never have reflogs. They also cannot be
> - updated through the normal ref update machinery. Instead,
> - they are updated by directly writing to the files. However,
> - they can be read as if they were refs, so `git rev-parse
> - MERGE_HEAD` will work.
> +[[def_pseudoref]]pseudoref ref::
shouldn't this just be 'pseudoref'?
Show 38 quoted lines
> + A ref that has different semantics than normal refs. These refs can be
> + accessed via normal Git commands but may not behave the same as a
> + normal ref in some cases.
> ++
> +The following pseudorefs are known to Git:
> +
> + - "`FETCH_HEAD`" is written by linkgit:git-fetch[1] or linkgit:git-pull[1]. It
> + may refer to multiple object IDs. Each object ID is annotated with metadata
> + indicating where it was fetched from and its fetch status.
> +
> + - "`MERGE_HEAD`" is written by linkgit:git-merge[1] when resolving merge
> + conflicts. It contains all commit IDs which are being merged.
>
> [[def_pull]]pull::
> Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and
> @@ -638,20 +636,6 @@ The most notable example is `HEAD`.
> An <<def_object,object>> used to temporarily store the contents of a
> <<def_dirty,dirty>> working directory and the index for future reuse.
>
> -[[def_special_ref]]special ref::
> - A ref that has different semantics than normal refs. These refs can be
> - accessed via normal Git commands but may not behave the same as a
> - normal ref in some cases.
> -+
> -The following special refs are known to Git:
> -
> - - "`FETCH_HEAD`" is written by linkgit:git-fetch[1] or linkgit:git-pull[1]. It
> - may refer to multiple object IDs. Each object ID is annotated with metadata
> - indicating where it was fetched from and its fetch status.
> -
> - - "`MERGE_HEAD`" is written by linkgit:git-merge[1] when resolving merge
> - conflicts. It contains all commit IDs which are being merged.
> -
> [[def_submodule]]submodule::
> A <<def_repository,repository>> that holds the history of a
> separate project inside another repository (the latter of
> --
> 2.45.0
Karthik Nayak <karthik.188@gmail.com>