On Thu, Feb 10, 2022 at 7:28 PM Junio C Hamano <gitster@xxxxxxxxx> wrote:
>
> Han-Wen Nienhuys <hanwen@xxxxxxxxxx> writes:
>
> > On Thu, Feb 10, 2022 at 5:36 PM Junio C Hamano <gitster@xxxxxxxxx> wrote:
> >> >> One thing that makes me worried somewhat is what I did not touch,
> >> >> namely, how pseudo refs are defined. I know MERGE_HEAD is very
> >> >> special and it may be impossible to coax it into refs API for
> >> >> writing, so the text there makes sense for it, but there are
> >> >> other all-caps-and-directly-under-dot-git-directory files like
> >> >> ORIG_HEAD and CHERRY_PICK_HEAD that are written using the refs
> >> >> API, so the description would have to be updated there.
> >> >
> >> > I'm not quite following; why would the description need to be updated?
> >> > Sure MERGE_HEAD is written without using the refs API, but we didn't
> >> > mention how the pseduorefs were written in the description, and all of
> >> > MERGE_HEAD, CHERRY_PICK_HEAD, ORIG_HEAD, REVERT_HEAD get written
> >> > per-worktree so doesn't "pseudorefs like MERGE_HEAD" cover it as far
> >> > as the reader is concerned?
> >>
> >> Here is how pseudo refs are defined.
> >>
> >> [[def_pseudoref]]pseudoref::
> >> 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. Pseudorefs both have names that 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
> >
> > refs.c says
> >
> > if (is_pseudoref_syntax(refname))
> > return REF_TYPE_PSEUDOREF;
> >
> > Ie. ref_type("HEAD") == REF_TYPE_PSEUDOREF
> >
> > This may be partly my fault (commit 55dd8b910 "Make HEAD a PSEUDOREF
> > rather than PER_WORKTREE.").
> >
> > From the source code I had only understood that pseudorefs are ALLCAPS
> > names and are in the toplevel namespace.
> > (HEAD, FETCH_HEAD and MERGE_HEAD have special-cased support in various places).
> >
> > Is this glossary the official definition of what things are? If so,
> > the source code should refer to there. If not -except for confusion-
> > how bad is it if the info in the glossary is inaccurate?
>
> Developer and end-user confusion ensues.
that's why I said: "except for confusion" :-)
I'm asking to understand if there is anything stopping us from
changing the glossary to match the current code.
> For backward compatibility, "git merge FETCH_HEAD" still may have to
> work the way it does (i.e. if FETCH_HEAD has multiple lines, the
> resulting merge would become an octopus merge, and merge message
> will say not just the commit but mention where they came from). But
> I am not sure if it is essential for us to keep treating these
> oddball temporary files as if they are (sort of) refs.
on a tangent: I posted a patch to write MERGE_AUTOSTASH,
rebase-merge/autostash, etc. as refs.
Is that the right direction? They are read like refs, but they are
together in a directory with other bits of stateful data (similar to
what is appended to FETCH_HEAD). Perhaps I should rather change the
read path, so they're always read as files rather than refs?
--
Han-Wen Nienhuys - Google Munich
I work 80%. Don't expect answers from me on Fridays.
--
Google Germany GmbH, Erika-Mann-Strasse 33, 80636 Munich
Registergericht und -nummer: Hamburg, HRB 86891
Sitz der Gesellschaft: Hamburg
Geschäftsführer: Paul Manicle, Halimah DeLaine Prado
