Re: [PATCH 1/9] refs: Introduce pseudoref and per-worktree ref concepts

[Eric Sunshine <sunshine@sunshineco.com>]

On Fri, Jul 24, 2015 at 12:45 AM, David Turner <dturner@twopensource.com> wrote:
> Add glossary entries for both concepts.
>
> Pseudorefs and per-worktree refs do not yet have special handling,
> because the files refs backend already handles them correctly.  Later,
> we will make the LMDB backend call out to the files backend to handle
> per-worktree refs.
>
> Signed-off-by: David Turner <dturner@twopensource.com>
> ---
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index ab18f4b..d04819e 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -411,6 +411,23 @@ exclude;;
>         core Git. Porcelains expose more of a <<def_SCM,SCM>>
>         interface than the <<def_plumbing,plumbing>>.
>
> +[[def_per_worktree_ref]]per-worktree ref::
> +       Refs that are per-<<def_worktree,worktree>>, rather than
> +       global.  This is presently only <<def_HEAD,HEAD>>, but might
> +       later include other unsuual refs.
> +
> +[[def_pseudoref]]pseudoref::
> +       Files under `$GIT_DIR` whose names are all-caps, and that
> +       contain a line consisting of a <<def_sha1,SHA-1>> followed by
> +       a newline, and optionally some additional data.  `MERGE_HEAD`
> +       and `CHERRY_PICK_HEAD` are examples.  Unlike
> +       <<def_per_worktree_ref,per-worktree refs>>, these files cannot
> +       be symbolic refs, and never not have reflogs.  They also

s/never not/never/

> +       cannot be updated through the normal ref update machinery.
> +       Instead, they are updated by directly writing to the files.
> +       However, they can be read as if they were refs, so `git
> +       rev-parse MERGE_HEAD` will work.
> +
>  [[def_pull]]pull::
>         Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and
>         <<def_merge,merge>> it.  See also linkgit:git-pull[1].