On Thu, Feb 10, 2022 at 8:35 AM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > Elijah Newren <newren@xxxxxxxxx> writes: > > >> 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 > optionally contain 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. > > Points that may need to be looked at in the world where files > backend is not the only ref backend are: Ah, sorry, I assumed in "the description would have to be updated there" you used "there" to refer to some part of your new patch text. Re-reading, I can see you did specify the pseudoref section, but I just somehow missed it. Sorry about that. > - "are ... files under `$GIT_DIR`" may no longer be true, once some > of them are stored in reftable, for example. > > - "followed by whitespace" may be an irrelevant detail for the > purpose of this paragraph. > > - CHERRY_PICK_HEAD, as written in sequencer.c::do_pick_commit(), > use update_ref() to write a named file out, so "followed by > whitesspace" (and other cruft, like MERGE_HEAD does) certainly > does not apply. > > - Also "cannot be updated through the normal ref update machinery" > is no longer true. sequencer.c::do_pick_commit() even calls > update_ref() with REF_NO_DEREF to ensure "cannot be symbolic > refs". > > - "never have reflogs" would make sense for the current set of > pseudorefs (does reflog on CHERRY_PICK_HEAD, for example, have > real use case?), but I do not know if it stays that way. I do > not care too deeply either way, but I want to avoid over > specifying things. > > What worries me the most is that we cannot simply say "all-caps > names that end with '_HEAD' all behave like refs except that they > will not be symrefs without reflog." MERGE_HEAD is the only known > exception if I am not mistaken, and I am OK to single it out as an > oddball. The current description however gives that there are a lot > more differences _among_ pseudorefs. Makes sense; thanks for clarifying for me.
