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: - "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.
