Re: How to display "HEAD~*" in "git log"

[Jeff King <peff@peff.net>]

On Wed, Jul 06, 2022 at 09:21:49PM +0300, Konstantin Khomoutov wrote:

> > Right. The problem is that it gets the set of possible ref tips with
> > for_each_ref(), which will not include HEAD. And then worse, since the
> > argument to "--refs" is a pattern, it matches junk like origin/HEAD.
> 
> Do I assume correctly that `git for-each-ref HEAD` does nothing, successfully,
> for the very same reason?

Yes.

> If so, I wonder if this should be somehow reflected in the docs.
> I mean, I have always maintained an impression that things like HEAD,
> ORIGIN_HEAD, FETCH_HEAD etc are also "refs" - because they, well, reference
> commits or branches.
> 
> The gitglossary manual page of my Git 2.30.2 states that
> 
> | ref
> |   A name that begins with refs/ (e.g. refs/heads/master)
> | <...>
> |   There are a few special-purpose refs that do not begin with refs/.
> |   The most notable example is HEAD.
> 
> which suggests that HEAD is a ref.

Yeah, I think the situation around those top-level names
is...complicated. They act like refs when you name them, but they are
often omitted from iteration of refs. And yet many spots (e.g.,
"rev-list --all") will include them explicitly. Documentation aside, I
would not be surprised if there are still places in the code itself
where there are inconsistencies. I feel like we've had a number of
"oops, include HEAD in this corner case" patches pop up over the years.
Maybe we've gotten them all now?

All of which is to say: you're definitely not wrong, but I'm not sure
what simple documentation change would be helpful. The handling of HEAD
in each specific situation could be mentioned in their respective
documentation spots, but identifying all of those is tough. Possibly the
glossary entry should say something like:

  Note that HEAD is sometimes includes in sets of refs (e.g., in `git
  rev-list --all`) and sometimes not (e.g., in `git for-each-ref`).

but that may be too vague to be helpful to anybody.

-Peff