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

[David Turner <dturner@twopensource.com>]

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>
---
 Documentation/glossary-content.txt | 17 +++++++++++++++++
 refs.c                             | 23 +++++++++++++++++++++++
 refs.h                             |  2 ++
 3 files changed, 42 insertions(+)

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
+	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].
diff --git a/refs.c b/refs.c
index 0b96ece..d31ca42 100644
--- a/refs.c
+++ b/refs.c
@@ -3857,6 +3857,29 @@ void ref_transaction_free(struct ref_transaction *transaction)
 	free(transaction);
 }
 
+int is_per_worktree_ref(const char *refname)
+{
+	return !strcmp(refname, "HEAD");
+}
+
+static int is_pseudoref(const char *refname)
+{
+	const char *c;
+
+	if (strchr(refname, '/'))
+		return 0;
+
+	if (is_per_worktree_ref(refname))
+		return 0;
+
+	for (c = refname; *c; ++c) {
+		if (!isupper(*c) && *c != '-' && *c != '_')
+			return 0;
+	}
+
+	return 1;
+}
+
 static struct ref_update *add_update(struct ref_transaction *transaction,
 				     const char *refname)
 {
diff --git a/refs.h b/refs.h
index e4e46c3..bd5526e 100644
--- a/refs.h
+++ b/refs.h
@@ -445,6 +445,8 @@ extern int parse_hide_refs_config(const char *var, const char *value, const char
 
 extern int ref_is_hidden(const char *);
 
+int is_per_worktree_ref(const char *refname);
+
 enum expire_reflog_flags {
 	EXPIRE_REFLOGS_DRY_RUN = 1 << 0,
 	EXPIRE_REFLOGS_UPDATE_REF = 1 << 1,
-- 
2.0.4.315.gad8727a-twtrsrc