[PATCH v2 3/5] doc: stop calling root refs pseudorefs
- From
Andy Koppe <andy.koppe@gmail.com>
- Date
- Nov 1, 2026, 23:03 UTC
- Message-ID
- <20261101230326.3675597-4-andy.koppe@gmail.com>
- In-Reply-To
- <20261022212903.177261-1-andy.koppe@gmail.com>
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.
In git-ls-remote(1), describe --refs as omitting refs outside "refs/", since that is what it actually checks. In the example, refer to HEAD, which is the only root ref that git-upload-pack(1) advertises. While there, correct "symbolics" to "symbolic refs".
In git-update-ref(1), drop the incorrect mention of ORIG_HEAD. HEAD is the only root ref that gets a reflog by default. In the description of core.logAllRefUpdates, correct the claim that "always" only applies to refs under "refs/". It applies to root refs too.
Distinguish root refs and pseudorefs in gitdatamodel(7). Lowercase the "other references" list entry there to match the others.
Signed-off-by: Andy Koppe <andy.koppe@gmail.com> --- Documentation/config/core.adoc | 2 +- Documentation/for-each-ref-options.adoc | 2 +- Documentation/git-ls-remote.adoc | 4 ++-- Documentation/git-update-ref.adoc | 13 ++++++------- Documentation/git-worktree.adoc | 13 ++++++++----- Documentation/gitdatamodel.adoc | 18 ++++++++++++++---- Documentation/rev-list-options.adoc | 4 ++-- 7 files changed, 34 insertions(+), 22 deletions(-)
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`. + This information can be used to determine what commit was the tip of a branch "2 days ago". diff --git a/Documentation/for-each-ref-options.adoc b/Documentation/for-each-ref-options.adoc index 54e2fa95c2..2b6d4ede0b 100644 --- a/Documentation/for-each-ref-options.adoc +++ b/Documentation/for-each-ref-options.adoc @@ -73,7 +73,7 @@ TAB %(refname)`. using the same rules as _<pattern>_ above. `--include-root-refs`:: - List root refs (`HEAD` and pseudorefs) apart from regular refs. + Also list root refs, such as `HEAD` or `ORIG_HEAD`. `--start-after=<marker>`:: Allows paginating the output by skipping references up to and including the 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/`. -q:: --quiet:: @@ -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: + ---- 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: oldsha1 SP newsha1 SP committer LF diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc index e6e77252ab..ba620d8ace 100644 --- a/Documentation/git-worktree.adoc +++ b/Documentation/git-worktree.adoc @@ -303,11 +303,14 @@ but others are specific to an individual worktree. One example is `HEAD`, which is different for each worktree. This section is about the sharing rules and how to access refs of one worktree from another. -In general, all pseudo refs are per-worktree and all refs starting with -`refs/` are shared. Pseudo refs are ones like `HEAD` which are directly -under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions, -however: refs inside `refs/bisect`, `refs/worktree` and `refs/rewritten` are -not shared. +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/` Refs that are per-worktree can still be accessed from another worktree via two special paths, `main-worktree` and `worktrees`. The former gives diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc index 8d9be02036..6958ac033c 100644 --- a/Documentation/gitdatamodel.adoc +++ b/Documentation/gitdatamodel.adoc @@ -211,15 +211,25 @@ 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:: 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`. + +[[root-refs]] +root refs:: + Git may also create references other than `HEAD` at the root of the + hierarchy, for example `ORIG_HEAD` or `REBASE_HEAD`. + +[[pseudorefs]] +pseudorefs:: + linkgit:git-fetch[1] and linkgit:git-merge[1] create the so-called + pseudorefs `FETCH_HEAD` and `MERGE_HEAD`. They are not references as + such, as they are not stored in the same way, but they can nevertheless + be used to refer to objects in commands such as linkgit:git-log[1] and + linkgit:git-diff[1]. NOTE: Git may delete objects that aren't "reachable" from any reference or <<reflogs,reflog>>. 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 when the index has unmerged entries. This option can be used to show relevant commits when resolving conflicts from a 3-way merge.
-- 2.56.0