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

[David Turner <dturner@twopensource.com>]

On Fri, 2015-07-24 at 12:20 -0700, Junio C Hamano wrote:
> David Turner <dturner@twopensource.com> writes:
> 
> > +[[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...
> 
> I wonder if you meant to include FETCH_HEAD in this category (I am
> not complaining about not having it listed as an example).  If you
> did mean to include FETCH_HEAD, then "followed-by a newline" must
> be rethought.

I guess "followed by whitespace"?

> Documentation pedant might say that the above definition would throw
> HEAD into this category.  s/all-caps,/all-caps (except "HEAD"),/ or
> something like that may be needed to prevent them from making useless
> noise.

I meant "and that contain a line consisting of a SHA" to exclude HEAD,
but I need to add a "always" in there, since detached HEAD would
otherwise apply.  That is, it is an additional condition on what a
pseudoref is.

Something like the following?

	Pseudorefs are a class of files under `$GIT_DIR` which behave
	like refs for the purposes of rev-parse, but which are treated
	specially by git.  Psuedorefs both have names are all-caps,
	and always start with a line consisting of a
	<<def_sha1,SHA-1>> followed by whitespace.  So, HEAD is not a
	pseudoref, because it is sometimes a symbolic ref.  They might
	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 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.