Re: [PATCH v3 3/5] doc: stop calling root refs pseudorefs

[Junio C Hamano <gitster@pobox.com>]

Andy Koppe <andy.koppe@gmail.com> writes:

> Several manual pages still use "pseudoref" in its old sense of any ref
> outside of "refs/", which the glossary now calls a root ref. Pseudorefs
> have since been restricted to FETCH_HEAD and MERGE_HEAD, which are not
> considered root refs.
>
> Replace "pseudoref" with "root ref" in those pages, giving HEAD and
> ORIG_HEAD as examples. In git-worktree(1), say that both root refs and
> pseudorefs are per-worktree, and drop the description of them as being
> directly under $GIT_DIR, because that does not apply to the reftable
> backend.

Thanks.  Clarification of this kind is very very much appreciated.

> diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc
> index bdc74d291c..8f8fe36a58 100644
> --- a/Documentation/config/core.adoc
> +++ b/Documentation/config/core.adoc
> @@ -376,7 +376,7 @@ core.logAllRefUpdates::
>  	`refs/heads/`), remote refs (i.e. under `refs/remotes/`),
>  	note refs (i.e. under `refs/notes/`), and the symbolic ref `HEAD`.
>  	If it is set to `always`, then a missing reflog is automatically
> -	created for any ref under `refs/`.
> +	created for any ref, including root refs such as `ORIG_HEAD`.

We are witnessing a grave mistake getting corrected here.  Nice.

>  `--include-root-refs`::
> -	List root refs (`HEAD` and pseudorefs) apart from regular refs.
> +	Also list root refs, such as `HEAD` or `ORIG_HEAD`.

Good.

> diff --git a/Documentation/git-ls-remote.adoc b/Documentation/git-ls-remote.adoc
> index d71c4ab3e2..7ce7df3149 100644
> --- a/Documentation/git-ls-remote.adoc
> +++ b/Documentation/git-ls-remote.adoc
> @@ -35,7 +35,7 @@ OPTIONS
>  	with other git subcommands.
>  
>  --refs::
> -	Do not show peeled tags or pseudorefs like `HEAD` in the output.
> +	Do not show peeled tags or refs outside `refs/`.

Hmph, is there a reason for saying "refs outside `refs/`" (as
opposed to "root refs") here?

I _think_ (correct me if I am not remembering right) by default
ls-remote shows everything under refs/ (with peeled tags) and HEAD.
It is not even "normal refs including root refs", i.e. ORIG_HEAD is
not shown.  With "--refs", of course ORIG_HEAD is still not shown,
but it stops HEAD from getting shown.  So "do not show root refs" or
"do not show refs outside refs/" are equally slightly broader than
needed (meaning: with or without this option restricting further,
any root ref other than HEAD, like ORIG_HEAD, are not shown anyway).

Do we even say what are normally shown in this manual page?  Perhaps
we would want to update the description to say something like

    DESCRIPTION
    -----------
    Displays references available in a remote repository along with
    the associated commit IDs.  By default, all normal refs under
    `refs/` and `HEAD` are shown.  For each tag object, the tag
    itself and the object it tags (colloquially called `peeled`) are
    shown.

upfront, before going to the OPTIONS section to tell the users how
to tweak that default?

> @@ -118,7 +118,7 @@ line shows the name of the object the tag points at.
>  EXAMPLES
>  --------
>  
> -* List all references (including symbolics and pseudorefs), peeling
> +* List all references (including `HEAD` and symbolic refs), peeling
>    tags:

Here, mentioning symbolic refs as if they are anything special is
misleading, no?  Symbolic or non-symbolic, refs are refs.

On the other hand, "all references" should logically include
(normal) refs under `refs/` hierarchy plus "root refs", so "List all
references" is technically incorrect.  Perhaps give it a bit more
correction, e.g.,

    List all refs under `refs/` and `HEAD`, peeling tags.

which would make it in line with the updated DESCRIPTION suggested
above.

> diff --git a/Documentation/git-update-ref.adoc b/Documentation/git-update-ref.adoc
> index 37a5019a8b..c775334230 100644
> --- a/Documentation/git-update-ref.adoc
> +++ b/Documentation/git-update-ref.adoc
> @@ -163,13 +163,12 @@ still see a subset of the modifications.
>  
>  LOGGING UPDATES
>  ---------------
> -If config parameter "core.logAllRefUpdates" is true and the ref is one
> -under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref
> -like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then
> -`git update-ref` will append a line to the log file
> -"$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating
> -the log name) describing the change in ref value.  Log lines are
> -formatted as:
> +If config parameter "core.logAllRefUpdates" is true and the ref is
> +HEAD or one under "refs/heads/", "refs/remotes/" or "refs/notes/", or
> +if the file "$GIT_DIR/logs/<ref>" exists, then `git update-ref` will
> +append a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all
> +symbolic refs before creating the log name) describing the change in
> +ref value.  Log lines are formatted as:

This mention of files and lines may be obsolete in the world with
reftable, but I am perfectly fine to leave the correction on that
front to another series, and concentrate only on "what is a ref?
what is a root ref?  and what is a pseudoref?" clarification and
nothing else.  And for that purpose, the updated text is a perfect
fit.

> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> ...
> +In general, all root refs and pseudorefs are per-worktree and all refs
> +starting with `refs/` are shared, except for refs with the following prefixes:
> +
> + - `refs/bisect/`
> +
> + - `refs/rewritten/`
> +
> + - `refs/worktree/`

Good; the same comment on "are these frozen?" applies.

> diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
> index 8d9be02036..2e44cc5003 100644
> --- a/Documentation/gitdatamodel.adoc
> +++ b/Documentation/gitdatamodel.adoc
> @@ -211,15 +211,28 @@ remote-tracking branches: `refs/remotes/<remote>/<branch>`::
>  default branch. This is the branch that `git clone` checks out by default.
>  
>  [[other-refs]]
> -Other references::
> +other references::

Nice attention to the detail.

>      Git tools may create references anywhere under `refs/`.
>      For example, linkgit:git-stash[1], linkgit:git-bisect[1],
>      and linkgit:git-notes[1] all create their own references
>      in `refs/stash`, `refs/bisect`, etc.
>      Third-party Git tools may also create their own references.
> -+
> -Git may also create references other than `HEAD` at the base of the
> -hierarchy, like `ORIG_HEAD`.

Good to get rid of this and adding a separate entry for root refs.

> +
> +[[root-refs]]
> +root refs::
> +    Git may create references other than `HEAD` at the root of the hierarchy,
> +    for example `ORIG_HEAD` or `REBASE_HEAD`.

Is this a good place to talk about their naming conventions?  At
least we want to have a reference to where we talk about it, I
think, just like you did one for pseudorefs below.

> +[[pseudorefs]]
> +pseudorefs::
> +    linkgit:git-fetch[1], linkgit:git-merge[1] and linkgit:git-pull[1]
> +    create the so-called pseudorefs `FETCH_HEAD` and `MERGE_HEAD`.
> +    They are not references as such, because they are not stored by the
> +    ref backend, but they can nevertheless be used to refer to objects in
> +    commands such as linkgit:git-log[1] and linkgit:git-diff[1].
> +
> +See linkgit:gitglossary[7] for further details on root refs and
> +pseudorefs.

Great.  I do not see a need for so-called here.  As technical term,
pseudorefs, references, and root refs, all are officially sanctioned
words, and there is nothing so-called about them.

> diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
> index bd9f345690..822604278a 100644
> --- a/Documentation/rev-list-options.adoc
> +++ b/Documentation/rev-list-options.adoc
> @@ -350,8 +350,8 @@ Under `--pretty=reference`, this information will not be shown at all.
>  
>  `--merge`::
>  	Show commits touching conflicted paths in the range `HEAD...<other>`,
> -	where `<other>` is the first existing pseudoref in `MERGE_HEAD`,
> -	`CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works
> +	where `<other>` is the first of `MERGE_HEAD`, `CHERRY_PICK_HEAD`,
> +	`REVERT_HEAD` or `REBASE_HEAD` that exists. Only works

Phrasing "existing pseudoref" in the original was wrong, but the
updated text feels a bit incomplete.  "... where <other> is the
first ref among X, Y, ... Z that exist" or something like that?

Overall, very welcome clarificaiton.