[PATCH v4 0/5] root refs vs pseudorefs

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

Changes in v4:
- Glossary: stop contrasting pseudorefs with root refs, mention
  remote-tracking branches in the "ref" entry, and state that the list
  of per-worktree ref prefixes will not be extended.
- git-ls-remote(1): describe what is shown by default, including
  peeling, and describe --refs and the example in those terms.
- gitdatamodel(7): mention the root ref naming rules, and drop
  "so-called".
- Reword the description and error message of rev-list --merge.

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              |   9 +-
 Documentation/git-update-ref.adoc             |  13 +--
 Documentation/git-worktree.adoc               |  16 ++-
 Documentation/gitdatamodel.adoc               |  22 +++-
 Documentation/glossary-content.adoc           | 110 +++++++++++-------
 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, 174 insertions(+), 124 deletions(-)
 rename t/t4013/{diff.diff-tree_--cc_--summary_REVERSE => diff.diff-tree_--cc_--summary_REVERSE_HEAD} (73%)

Range-diff against v3:
1:  5630c671db ! 1:  e3f2ee816f doc: glossary: add root ref and clarify pseudorefs
    @@ Commit message
         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.
    +    irregular root refs there from the "ref" entry, and refer to
    +    gitrevisions(7) for descriptions of commonly used root refs. In the
    +    "ref" entry, mention remote-tracking branches alongside local branches
    +    and tags.
     
         Reword the "pseudoref" entry so that it no longer calls them refs, and
         explain how their additional semantics set them apart. Clarify what
    @@ Documentation/glossary-content.adoc: exclude;;
     -	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 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.
    ++	record more than one object ID and may carry extra metadata.
    ++	Therefore, pseudorefs are 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]
    @@ Documentation/glossary-content.adoc: The following pseudorefs are known to Git:
     +<<def_root_ref,root refs>>.
      +
      Different subhierarchies are used for different purposes. For example,
    - the `refs/heads/` hierarchy is used to represent local branches whereas
    +-the `refs/heads/` hierarchy is used to represent local branches whereas
     -the `refs/tags/` hierarchy is used to represent local tags..
    -+the `refs/tags/` hierarchy is used to represent local tags.
    ++local branches are stored under `refs/heads/`, remote-tracking branches
    ++under `refs/remotes/`, and tags under `refs/tags/`.
      +
      See also "REFERENCES" in linkgit:gitdatamodel[7].
      
    @@ Documentation/glossary-content.adoc: format. See linkgit:git-reflog[1] for detai
     + - `MERGE_AUTOSTASH`
     +--
     ++
    -+<<def_pseudoref,Pseudorefs>> are not considered root refs, even though
    -+they follow the naming rules.
    -++
    -+See linkgit:gitrevisions[7] for descriptions of commonly used root refs
    -+and pseudorefs.
    ++See linkgit:gitrevisions[7] for descriptions of commonly used root refs.
     +
      [[def_SCM]]SCM::
      	Source code management (tool).
2:  0bc902f13d ! 2:  ccc3554410 doc: glossary: update per-worktree refs
    @@ Commit message
         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,
    -    link to "per-worktree ref" instead of listing HEAD and MERGE_HEAD.
    +    Bring the list up to date, and state that it will not be extended, as
    +    new per-worktree refs are meant to go under "refs/worktree/" since
    +    8aff1a9ca5 (Add a place for (not) sharing stuff between worktrees,
    +    2018-09-29).
     
         Signed-off-by: Andy Koppe <andy.koppe@gmail.com>
     
    @@ Documentation/glossary-content.adoc: exclude;;
     + - `refs/worktree/`
     +--
     ++
    -+<<def_pseudoref,Pseudorefs>> are also specific to each worktree.
    ++This list will not be extended in future. Any new per-worktree refs shall be
    ++created under `refs/worktree/`.
    +++
    ++Even though they are not refs, <<def_pseudoref,pseudorefs>> are also
    ++specific to each worktree.
     ++
     +See "REFS" in linkgit:git-worktree[1] for how to access the
     +per-worktree refs of other worktrees.
      
      [[def_pseudoref]]pseudoref::
      	A name that can be used like a <<def_ref,ref>> to refer to an
    -@@ Documentation/glossary-content.adoc: and pseudorefs.
    +@@ Documentation/glossary-content.adoc: See linkgit:gitrevisions[7] for descriptions of commonly used root refs.
      	"working tree" and repository metadata, most of which are
      	shared among other worktrees of a single repository, and
      	some of which are maintained separately per worktree
3:  ac3ed53867 ! 3:  bc29d66748 doc: stop calling root refs pseudorefs
    @@ Commit message
         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.
    +    backend. As in the glossary, state that the list of per-worktree
    +    prefixes will not be extended.
     
    -    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-ls-remote(1), state that HEAD and refs under "refs/" are shown
    +    by default, and describe --refs and the example in those terms rather
    +    than in terms of pseudorefs. Say "object IDs" instead of "commit IDs",
    +    as tag objects are shown too.
     
         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
    @@ Documentation/for-each-ref-options.adoc: TAB %(refname)`.
          Allows paginating the output by skipping references up to and including the
     
      ## Documentation/git-ls-remote.adoc ##
    +@@ Documentation/git-ls-remote.adoc: SYNOPSIS
    + DESCRIPTION
    + -----------
    + Displays references available in a remote repository along with the associated
    +-commit IDs.
    ++object IDs. By default, `HEAD` and all refs under `refs/` are shown.
    ++Annotated tags are also shown peeled, i.e. recursively resolved to the objects
    ++they point at.
    + 
    + 
    + OPTIONS
     @@ Documentation/git-ls-remote.adoc: 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/`.
    ++	Do not show `HEAD` or peeled tags in the output.
      
      -q::
      --quiet::
    @@ Documentation/git-ls-remote.adoc: line shows the name of the object the tag poin
      --------
      
     -* List all references (including symbolics and pseudorefs), peeling
    -+* List all references (including `HEAD` and symbolic refs), peeling
    -   tags:
    +-  tags:
    ++* List `HEAD` and all refs under `refs/`, peeling tags:
      +
      ----
    + $ git ls-remote
     
      ## Documentation/git-update-ref.adoc ##
     @@ Documentation/git-update-ref.adoc: still see a subset of the modifications.
    @@ Documentation/git-worktree.adoc: but others are specific to an individual worktr
     + - `refs/rewritten/`
     +
     + - `refs/worktree/`
    ++
    ++This list will not be extended in future. Any new per-worktree refs shall be
    ++created under `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
    @@ Documentation/gitdatamodel.adoc: remote-tracking branches: `refs/remotes/<remote
     +[[root-refs]]
     +root refs::
     +    Git may create references other than `HEAD` at the root of the hierarchy,
    -+    for example `ORIG_HEAD` or `REBASE_HEAD`.
    ++    for example `ORIG_HEAD` or `REBASE_HEAD`. Their names must follow
    ++    special rules.
     +
     +[[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`.
    ++    create the 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.
    ++See linkgit:gitglossary[7] for the root ref naming rules and further details
    ++on pseudorefs.
      
      NOTE: Git may delete objects that aren't "reachable" from any reference
      or <<reflogs,reflog>>.
    @@ Documentation/rev-list-options.adoc: Under `--pretty=reference`, this informatio
      	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`,
    ++	where `<other>` is the first one 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.
4:  2c3f3ab195 ! 4:  610138169d refs: stop calling root refs pseudorefs
    @@ Commit message
         those root refs and restricts pseudorefs to FETCH_HEAD and MERGE_HEAD,
         so update them.
     
    +    The "--merge" error message called MERGE_HEAD, CHERRY_PICK_HEAD,
    +    REVERT_HEAD and REBASE_HEAD pseudorefs, but MERGE_HEAD is the only
    +    actual pseudoref among them, and merely listing their names suggests
    +    that one of them should be given as an argument. Instead, say that an
    +    ongoing merge, cherry-pick, revert or rebase is required.
    +
         Bash completion function __git_pseudoref_exists() is not renamed, as
         there is no obvious term covering both root refs and pseudorefs, and
         third-party completion scripts might depend on the name.
    @@ contrib/completion/git-completion.bash: __git_eread ()
     -# 1: The pseudo-ref to search
     +# Runs git in $__git_repo_path to determine whether a root ref or
     +# pseudoref exists.
    -+# 1: The ref to check
    ++# 1: The name to check
      __git_pseudoref_exists ()
      {
      	local ref=$1
    @@ refs.h: void update_ref_namespace(enum ref_namespace namespace, char *ref);
     - * "normal" refs. These refs can thus not be stored in the ref backend,
     - * but must always be accessed via the filesystem. The following refs
     - * are pseudorefs:
    -+ * Pseudorefs are names that can be used like refs, but have different
    ++ * Pseudorefs are names that can be used like refs, but have additional
     + * semantics. They cannot be stored in the ref backend, but must always
     + * be accessed via the filesystem. The following are pseudorefs:
       *
    @@ revision.c: static const char *lookup_other_head(struct object_id *oid)
      		}
      
     -	die(_("--merge requires one of the pseudorefs MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD or REBASE_HEAD"));
    -+	die(_("--merge requires one of MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD or REBASE_HEAD"));
    ++	die(_("--merge requires an ongoing merge, cherry-pick, revert or rebase"));
      }
      
      static void prepare_show_merge(struct rev_info *revs)
5:  d8a825d8cc = 5:  368ea8b6bc t: stop calling root refs pseudorefs
-- 
2.56.0