[PATCH v3 0/5] root refs vs pseudorefs

[Andy Koppe <andy.koppe@gmail.com>]

Changes in v3:
- Explain the additional semantics of pseudorefs in the glossary.
- Clarify the FETCH_HEAD and MERGE_HEAD descriptions.
- Point gitdatamodel(7) to the glossary for root refs and pseudorefs.
- Reword messages of commits 1 and 2.

Andy Koppe (5):
  doc: glossary: add root ref and clarify pseudorefs
  doc: glossary: update per-worktree refs
  doc: stop calling root refs pseudorefs
  refs: stop calling root refs pseudorefs
  t: stop calling root refs pseudorefs

 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               |  21 +++-
 Documentation/glossary-content.adoc           | 109 +++++++++++-------
 Documentation/rev-list-options.adoc           |   4 +-
 builtin/for-each-ref.c                        |   2 +-
 contrib/completion/git-completion.bash        |   7 +-
 refs.h                                        |  13 +--
 revision.c                                    |   2 +-
 t/show-ref-exists-tests.sh                    |   4 +-
 t/t0600-reffiles-backend.sh                   |   2 +-
 t/t0610-reftable-basics.sh                    |   2 +-
 t/t1400-update-ref.sh                         |  66 +++++------
 t/t1403-show-ref.sh                           |   2 +-
 t/t1460-refs-migrate.sh                       |   4 +-
 t/t4013-diff-various.sh                       |   6 +-
 ...iff.diff-tree_--cc_--summary_REVERSE_HEAD} |   2 +-
 t/t6302-for-each-ref-filter.sh                |   4 +-
 t/t9902-completion.sh                         |   4 +-
 22 files changed, 167 insertions(+), 121 deletions(-)
 rename t/t4013/{diff.diff-tree_--cc_--summary_REVERSE => diff.diff-tree_--cc_--summary_REVERSE_HEAD} (73%)

Range-diff against v2:
1:  c52fbbd369 ! 1:  5630c671db doc: glossary: add root ref and clarify pseudorefs
    @@ Commit message
         not actually name them "root refs", even though the term is used
         elsewhere, for example by "git for-each-ref --include-root-refs". It
         also defines pseudorefs as refs, yet is_root_ref() deliberately excludes
    -    them, as they are not stored or handled by the ref backends.
    +    them, as they are not stored or handled by the ref backend.
     
         Add a "root ref" entry, moving the naming rules and the list of
         irregular root refs there from the "ref" entry. State that pseudorefs
         are not root refs, and refer to gitrevisions(7) for descriptions of
         commonly used root refs and pseudorefs.
     
    -    Reword the "pseudoref" entry so that it no longer calls them refs, add
    -    git-for-each-ref(1) as another example of how they are not proper refs,
    -    and explain that using a pseudoref containing multiple object IDs yields
    -    the first one.
    +    Reword the "pseudoref" entry so that it no longer calls them refs, and
    +    explain how their additional semantics set them apart. Clarify what
    +    FETCH_HEAD records and what its "fetch status" annotation means, and
    +    that MERGE_HEAD is also written by git-pull(1) and not only for merge
    +    conflicts.
     
         Signed-off-by: Andy Koppe <andy.koppe@gmail.com>
     
    @@ Documentation/glossary-content.adoc: exclude;;
     -	read via normal Git commands, but cannot be written to by commands like
     -	linkgit:git-update-ref[1].
     +	A name that can be used like a <<def_ref,ref>> to refer to an
    -+	<<def_object,object>>, but that is not stored in the same way as refs.
    -+	For example, pseudorefs can be passed to linkgit:git-log[1] or
    -+	linkgit:git-diff[1], but they cannot be written by
    -+	linkgit:git-update-ref[1] or listed by linkgit:git-for-each-ref[1].
    ++	<<def_object,object>>, but that has additional semantics: it can
    ++	record more than one object ID and may carry extra metadata. In
    ++	contrast to <<def_root_ref,root refs>>, pseudorefs are therefore
    ++	not stored or handled by the ref backend.
    +++
    ++Pseudorefs can be passed to commands such as linkgit:git-log[1] or
    ++linkgit:git-diff[1], but cannot be written by linkgit:git-update-ref[1]
    ++or listed by linkgit:git-for-each-ref[1]. When a pseudoref contains more
    ++than one object ID, using it to refer to an object yields the first one.
      +
      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.
    ++ - `FETCH_HEAD` is written by linkgit:git-fetch[1] or linkgit:git-pull[1]
    ++   to record the objects that have been fetched. Each object is annotated
    ++   with the ref and repository it was fetched from and whether it is to be
    ++   merged when pulling.
      
    -  - `MERGE_HEAD` is written by linkgit:git-merge[1] when resolving merge
    -    conflicts. It contains all commit IDs which are being merged.
    -+--
    -++
    -+When a pseudoref contains more than one object ID, using it to refer to an
    -+object yields the first one.
    +- - `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.
    ++ - `MERGE_HEAD` is written by linkgit:git-merge[1] or linkgit:git-pull[1]
    ++   to record the commits being merged while a merge is in progress.
      
      [[def_pull]]pull::
      	Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and
2:  9e1ddc997c ! 2:  0bc902f13d doc: glossary: update per-worktree refs
    @@ Metadata
      ## Commit message ##
         doc: glossary: update per-worktree refs
     
    -    The "per-worktree ref" entry says that these are only HEAD and refs
    -    under "refs/bisect/", but that has been out of date since a9be29c981
    -    (sequencer: make refs generated by the `label` command worktree-local,
    -    2018-04-25). All root refs are per-worktree, as are refs under
    -    "refs/worktree/" and "refs/rewritten/". Pseudorefs are specific to each
    -    worktree too.
    +    The "per-worktree ref" entry says that only HEAD and refs under
    +    "refs/bisect/" are per-worktree, but that has been out of date since
    +    a9be29c981 (sequencer: make refs generated by the `label` command
    +    worktree-local, 2018-04-25). All root refs are per-worktree, as are refs
    +    under "refs/worktree/" and "refs/rewritten/". Pseudorefs are specific to
    +    each worktree too.
     
         Bring the list up to date, and refer to git-worktree(1) for how to
         access per-worktree refs of other worktrees. In the "worktree" entry,
    -    describe HEAD as a per-worktree ref and MERGE_HEAD as a pseudoref,
    -    rather than listing them separately from per-worktree refs.
    +    link to "per-worktree ref" instead of listing HEAD and MERGE_HEAD.
     
         Signed-off-by: Andy Koppe <andy.koppe@gmail.com>
     
3:  6711bf027d ! 3:  ac3ed53867 doc: stop calling root refs pseudorefs
    @@ Documentation/gitdatamodel.adoc: remote-tracking branches: `refs/remotes/<remote
     +
     +[[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`.
    ++    Git may 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].
    ++    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.
      
      NOTE: Git may delete objects that aren't "reachable" from any reference
      or <<reflogs,reflog>>.
4:  ea7baa1269 = 4:  2c3f3ab195 refs: stop calling root refs pseudorefs
5:  d11ab774ec = 5:  d8a825d8cc t: stop calling root refs pseudorefs
-- 
2.56.0