Andy Koppe [off-list ref] 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.
quoted hunk
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.
quoted hunk
`--include-root-refs`::
- List root refs (`HEAD` and pseudorefs) apart from regular refs.
+ Also list root refs, such as `HEAD` or `ORIG_HEAD`.
Good.
quoted hunk
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?
quoted hunk
@@ -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.
quoted hunk
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.
quoted hunk
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.
quoted hunk
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.
quoted hunk
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.
quoted hunk
+
+[[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.
quoted hunk
+[[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.
quoted hunk
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.