Subject: Re: [PATCH 0/5] make room for "special ref"

From: Patrick Steinhardt <[email-masked]>
Date: Mon, 18 Dec 2023 09:41:43 +0100

On Fri, Dec 15, 2023 at 04:44:47PM -0800, Junio C Hamano wrote:
> Ramsay Jones <[email-masked]> writes:
> 
> > Yes, I was going to suggest exactly this, after Patrick pointed out
> > that there were only two 'special psuedo-refs' (I had a vague feeling
> > there were some more than that) FETCH_HEAD and MERGE_HEAD.

I don't think there are more special refs than those two. Andy pointed
out CHERRY_PICK_HEAD and REVERT_HEAD, but both of them actually get
accessed via the ref backend exclusively and thus cannot be special in
any way. Also, the test suite of Git passes with only those two refs
marked as special refs with the reftable backend, which is another good
indicator that I didn't miss anything here because we definitely can't
store special information in the reftable backend.

It's of course still possible that our test suite has a blind spot and
that I missed any special refs. If so, I would love to hear about them.

> Glad to see that I am not alone.  We should be able to treat
> MERGE_HEAD similarly.  It is used to communicate the list of "other
> parents" from "git merge" that stops in the middle (either for merge
> conflict, or in response to the "--no-commit" command line option)
> to "git commit" that concludes such an unfinished merge.  Many
> commands merely use the presence of MERGE_HEAD as a sign that a
> merge is in progress (e.g. "git status"), which would not break if
> we just started to record the first parent in a pseudoref MERGE_HEAD
> and wrote the other octopus parents elsewhere, but some commands do
> need all these parents from MERGE_HEAD (e.g. "git blame" that
> synthesizes a fake starting commit out of the working tree state).

I would certainly love to drop the "specialness" of both FETCH_HEAD and
MERGE_HEAD, but I am a bit pessimistic about whether we really can. The
format of those refs has been around for quite a long time already, and
I do expect that there is tooling out there that parses those files.

I would claim that it's especially likely that FETCH_HEAD is getting
parsed by external tools. Historically, there has not been a way to
really figure out which refs have been updated in git-fetch(1). So any
scripts that perform a fetch and want to learn about what was updated
would very likely resort to parsing FETCH_HEAD. This has changed a bit
with the introduction of the machine-parsable interface of git-fetch(1),
but it has only been introduced rather recently with Git v2.42.

> If we cannot get rid of all "special refs" anyway, however, I think
> there is little that we can gain from doing such "make FETCH_HEAD
> and MERGE_HEAD into a single-object pseudoref, and write other info
> in separate files" exercise.  We can treat the current FETCH_HEAD
> and MERGE_HEAD as "file that is not and is more than a ref", which
> is what the current code is doing anyway, which means we would
> declare that they have to stay to be files under $GIT_DIR/ and will
> be accessed via the filesystem access.

I'd like for it to be otherwise, but I think this is the only sensible
thing to do. I think it was a mistake to introduce those special refs
like this and treat them almost like a real ref, but that's always easy
to say in hindsight.

> At that point, calling them "special ref" might even be more
> misleading than its worth and we may be better off to admit that they
> are not even refs but a datafile some commands can use to obtain input
> from, but the phrase we use to refer to them, be it "special ref" or
> some random datafile, does not make a fundamental change on anything.

Well, the problem is that these do indeed behave like a ref for most of
the part: you can ask for them via git-rev-parse(1) and we'll resolve
them just fine, even though we only ever return the first object ID. So
even though I'm not a huge fan of calling them "special ref", I think we
should at least highlight the reflike-nature in whatever we want to call
them.

Patrick