@feigi/fleet-ctl 3.26.0 → 3.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,8 @@
1
1
  # shellcheck shell=sh
2
2
  # Reading worktree state for the fleet's shell scripts: the porcelain listing,
3
- # path predicates more than one script asks, and in-progress operation state.
3
+ # path predicates more than one script asks, in-progress operation state, and
4
+ # the Registration probe — the verdicts every script that deletes a worktree or
5
+ # a branch, or reads an absence as "free", asks git before it acts.
4
6
  # Sourced, never executed — no shebang, and the `shell=sh` directive above is
5
7
  # what tells shellcheck what to check it as.
6
8
  #
@@ -596,3 +598,498 @@ EOF
596
598
  wt_err=
597
599
  return "$wt_rd_rc"
598
600
  }
601
+
602
+ # ---------------------------------------------------------------------------
603
+ # The Registration probe: every verdict a script asks of git about a worktree
604
+ # before it deletes one, a branch, or reads an absence as "free". One
605
+ # definition per verdict, so a fix lands once and reaches every caller.
606
+ #
607
+ # Contract shared by every function below. Each returns a status and writes
608
+ # named output variables; none prints, none exits, and none decides what a
609
+ # refusal means — the caller maps it onto its own reporting shape (keep a
610
+ # branch, die, block, record an unknown). A refusal's reason is prose in
611
+ # `$wt_why`, written to stand in a receipt field verbatim; each function
612
+ # clears `$wt_why` on entry, so it is empty after every answer that is not a
613
+ # refusal. Condition context only, like `gone`: a non-zero return exits a
614
+ # `set -e` caller.
615
+ #
616
+ # The outputs are read by the sourcing script and never again in here, which
617
+ # is what SC2034 sees on this file's standalone shellcheck run — the
618
+ # disables below, as for `wt_listing`.
619
+ # ---------------------------------------------------------------------------
620
+
621
+ # Is anything at all occupying $1? Not the same question as `gone`, which asks
622
+ # whether an absence is established; this one asks whether the path is taken.
623
+ # `-e` alone FOLLOWS symlinks, so a DANGLING one reads as absent while it still
624
+ # occupies the path and still fails the next `git worktree add` (`fatal: '...'
625
+ # already exists`) — and that is residue a removal can leave: where a symlink
626
+ # POINTS AT the registered worktree directory, `git worktree remove` deletes
627
+ # that directory and returns 0, leaving the link behind and now dangling (git
628
+ # 2.50.1).
629
+ wt_occupied() { [ -e "$1" ] || [ -L "$1" ]; }
630
+
631
+ # Resolve the worktree registry, `<git-common-dir>/worktrees`, into `$wt_root`
632
+ # once per run — the git dir does not move under a running script. 1 with
633
+ # `$wt_why` when git cannot name the common directory.
634
+ #
635
+ # `2>/dev/null`, never `2>&1`: the answer is used as a PATH, and a
636
+ # `~/.gitconfig` with a key outside any section makes every git command print
637
+ # `error: key does not contain a section: …` on stderr AT EXIT 0, which `2>&1`
638
+ # would glue in front of it.
639
+ wt_root=
640
+ # shellcheck disable=SC2034
641
+ wt_registry_root() {
642
+ wt_why=
643
+ [ -z "$wt_root" ] || return 0
644
+ if ! wt_rr_common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null); then
645
+ wt_why="cannot resolve the git common directory"
646
+ return 1
647
+ fi
648
+ wt_root="$wt_rr_common/worktrees"
649
+ }
650
+
651
+ # Count the registry entries on disk into `$wt_registered`.
652
+ #
653
+ # `worktree list --porcelain` reads `<git-common-dir>/worktrees`, the admin
654
+ # directory git writes one subdir per linked worktree into. When that
655
+ # directory — or any file git needs inside one of its entries — cannot be read,
656
+ # git does not error: it silently drops the affected entries and still exits 0
657
+ # (git 2.50.1). Predicting which reads git needs is one level too shallow:
658
+ # `chmod 000` on the `gitdir` FILE inside an entry passes every permission test
659
+ # a script could make on the entry itself and still drops the worktree from the
660
+ # listing — measured. So count instead: one registry entry on disk per linked
661
+ # worktree, against what git reported.
662
+ #
663
+ # Absent entirely answers nothing: a repo whose worktrees were removed and
664
+ # pruned (or never existed) has no `worktrees` dir, and zero entries against
665
+ # the main worktree alone is a match. Present but unreadable is a refusal, and
666
+ # not redundant with the count: unreadable, the glob below expands to nothing,
667
+ # and zero-on-disk would AGREE with the empty listing git returns for the same
668
+ # reason. `-d` joins `-r` and `-x` there because a registry replaced by a
669
+ # mode-755 FILE passes both, globs to nothing, counts 0 against git's 0, and
670
+ # agrees.
671
+ #
672
+ # A registry entry is a directory; anything else in here is not git's. And an
673
+ # EMPTY directory is skipped: that is an operator's stray `mkdir`, which git
674
+ # ignores — counting one refuses every pass in the repo, forever (measured, git
675
+ # 2.50.1: git lists 2 worktrees where a bare `-d` count said 2 registered
676
+ # against 1 linked). Emptiness, NOT the absence of a `gitdir` file: git drops
677
+ # an entry whose `gitdir` was deleted, so keying the skip on that file lets the
678
+ # entry through as "not git's" and the counts agree over a checkout that may
679
+ # still be on disk (measured: listed 1 → linked 0, and a gitdir-keyed count
680
+ # returns 0 to match). A corrupt entry still holds git's own files —
681
+ # commondir, HEAD, index, logs, refs — so emptiness separates it from a stray.
682
+ #
683
+ # `ls`'s STATUS, not just its output: an entry that could not be LISTED is not
684
+ # an empty one, and `2>/dev/null` hides the difference. A stray `mkdir` lists
685
+ # empty at rc 0; an entry chmod'd 000 or 0111 fails EACCES and prints nothing
686
+ # just the same. Reading only the output skips that entry — and git drops it
687
+ # too, so the counts AGREE over a member's uncommitted work (measured, against
688
+ # release-ticket.sh: exit 0, `released:true`, branch deleted). Could not read
689
+ # it, so it is counted, and the mismatch refuses.
690
+ # shellcheck disable=SC2034
691
+ wt_count_registry() {
692
+ wt_registered=0
693
+ wt_registry_root || return 1
694
+ [ -e "$wt_root" ] || return 0
695
+ [ -d "$wt_root" ] && [ -r "$wt_root" ] && [ -x "$wt_root" ] || {
696
+ wt_why="worktree registry $wt_root could not be read"
697
+ return 1
698
+ }
699
+ for wt_cr_entry in "$wt_root"/*; do
700
+ [ -d "$wt_cr_entry" ] || continue
701
+ if wt_cr_ls=$(ls -A "$wt_cr_entry" 2>/dev/null) && [ -z "$wt_cr_ls" ]; then continue; fi
702
+ wt_registered=$((wt_registered + 1))
703
+ done
704
+ return 0
705
+ }
706
+
707
+ # Count the linked worktrees in `$wt_list` as it stands into `$wt_linked`.
708
+ #
709
+ # awk, not `grep -c … || true`: `grep -c` exits 1 on zero matches, and the
710
+ # `|| true` that absorbs it absorbs a grep that could not RUN just as happily,
711
+ # leaving the count empty and `$((listed - 1))` at -1. This program holds no
712
+ # `exit`, so its status is the counter's own. The main worktree is always
713
+ # listed first and has no registry entry of its own, hence the -1 — and the
714
+ # `-ge 1` floor, because a listing with no main checkout at all comes only
715
+ # from a broken or shimmed git and reads as -1 linked otherwise. A newline
716
+ # inside a path never moves this count: `wt_listing` has already swapped it,
717
+ # so every record contributes exactly one `worktree ` line.
718
+ # shellcheck disable=SC2034
719
+ wt_count_linked() {
720
+ if ! wt_cl_n=$(printf '%s\n' "$wt_list" | LC_ALL=C awk '/^worktree /{c++} END{print c+0}'); then
721
+ wt_why="could not count the worktrees git listed"
722
+ return 1
723
+ fi
724
+ if [ "$wt_cl_n" -lt 1 ]; then
725
+ wt_why="git listed no worktrees at all — not even the main checkout, so the listing cannot be trusted"
726
+ return 1
727
+ fi
728
+ wt_linked=$((wt_cl_n - 1))
729
+ }
730
+
731
+ # One count pair: the registry first, then a fresh listing, then its count.
732
+ # 0 counted (agreeing or not), 1 a count refused (`$wt_why`), 2 the listing
733
+ # could not be read (`$wt_why` carries `$wt_err`).
734
+ wt_count_pair() {
735
+ wt_count_registry || return 1
736
+ if ! wt_listing; then
737
+ wt_why=$(printf '%s' "$wt_err" | tr '\n' ' ')
738
+ return 2
739
+ fi
740
+ wt_count_linked || return 1
741
+ }
742
+
743
+ # Is the listing COMPLETE — does git list exactly as many linked worktrees as
744
+ # the registry holds entries? A listing that silently dropped an entry hands
745
+ # every lookup over it "no worktree" for a branch a live worktree holds, at
746
+ # rc 0, so its absences cannot be trusted until this agrees.
747
+ #
748
+ # Reads the listing itself, through `wt_listing`, and leaves it in `$wt_list`:
749
+ # the caller's lookups then scan the very listing the counts validated. Sets
750
+ # `$wt_registered`, `$wt_linked` and `$wt_root`.
751
+ #
752
+ # 0: the counts agree.
753
+ # 1: refused — `$wt_why` names the cause: the common directory or the
754
+ # registry could not be read, the listing could not be counted, or the
755
+ # counts still disagree, named by the DIRECTION observed. FEWER listed than
756
+ # registered is git dropping an entry it could not read — the fault this
757
+ # check exists to catch. MORE listed than registered is the reverse, the
758
+ # registry read missing entries, which under a parallel fleet is a
759
+ # sibling's `git worktree add` landing between the two reads. One message
760
+ # cannot serve both: they send the reader to opposite places.
761
+ # 2: the listing itself could not be read — `$wt_why` is `wt_listing`'s cause,
762
+ # flattened to one line, and `$wt_err` holds it as read.
763
+ #
764
+ # Recount before refusing. The registry scan and git's listing are two reads
765
+ # at two instants, not one atomic read, and a sibling agent's `git worktree
766
+ # add` or `remove` landing in the gap makes them disagree with nothing wrong —
767
+ # measured on the per-script copy of this recount that release-ticket.sh once
768
+ # held: 3/100 dry-run releases aborted on the cross-check under a throttled
769
+ # churner, 48-66/80 unthrottled, all with zero real faults. A mismatch
770
+ # therefore re-takes BOTH counts, in the same order — registry first, listing
771
+ # second. Re-taking the registry alone leaves the linked count pinned to the
772
+ # first listing, and a second mutation landing after that listing inflates the
773
+ # registry count and flips which direction is reported (measured on the copy
774
+ # inflight.sh once held). A mutation landing between a pair's registry count
775
+ # and its listing is already reflected in that listing, so a re-taken pair
776
+ # needs a mutation inside its own narrower window to escape (measured on that
777
+ # inflight.sh copy while it re-took the registry alone: 1.99% -> 0.00% at 2
778
+ # mutations/s, 56.6% -> 1.29% saturated).
779
+ #
780
+ # That window is still a gap between two reads, so a further mutation inside a
781
+ # re-taken pair escapes it the same way; closing that for good would need an
782
+ # atomic snapshot of registry and listing together, which git does not offer.
783
+ # Each extra pass demands one more precisely-timed mutation to defeat, while a
784
+ # genuinely dropped entry is a standing state that survives every pass — so
785
+ # the re-take is bounded at two passes (`wt_counts_passes`) rather than chased.
786
+ # A false refusal costs one wait; a guessed agreement costs a deletion.
787
+ wt_counts_passes=2
788
+ # shellcheck disable=SC2034
789
+ wt_counts() {
790
+ wt_why=
791
+ wt_count_pair || return $?
792
+ wt_ct_left=$wt_counts_passes
793
+ while [ "$wt_linked" -ne "$wt_registered" ] && [ "$wt_ct_left" -gt 0 ]; do
794
+ wt_count_pair || return $?
795
+ wt_ct_left=$((wt_ct_left - 1))
796
+ done
797
+ if [ "$wt_linked" -lt "$wt_registered" ]; then
798
+ wt_why="git listed $wt_linked worktrees for $wt_registered registry entries in $wt_root — the listing is incomplete, so no absence it reports can be trusted"
799
+ return 1
800
+ elif [ "$wt_linked" -gt "$wt_registered" ]; then
801
+ wt_why="git listed $wt_linked worktrees but only $wt_registered registry entries were counted in $wt_root — the registry read missed entries git can see, so no absence it reports can be trusted"
802
+ return 1
803
+ fi
804
+ return 0
805
+ }
806
+
807
+ # Does $1's `.git` linkage answer for $1 itself? 0 when it does; 1 with
808
+ # `$wt_why` when git cannot answer through it, when it answers for another
809
+ # directory, when $1 is itself a symlink, or when `[` cannot evaluate the
810
+ # compare. Call it once the caller has established the linkage EXISTS (a
811
+ # regular `$1/.git` file), and before any git command run through $1 is
812
+ # believed — the dirty check first among them.
813
+ #
814
+ # Existing is not answering. Two shapes keep `.git` a well-formed regular file
815
+ # and move git's WORKING TREE elsewhere: a `.git` naming a foreign git dir not
816
+ # called `.git` whose `core.worktree` is another directory, and `core.worktree`
817
+ # set in the worktree's own `config.worktree` under `extensions.worktreeConfig`,
818
+ # `.git` untouched. `git -C "$1" status` then reads THAT tree, so a clean one
819
+ # there reads clean over the work sitting in $1 (measured on both shapes, git
820
+ # 2.50.1). `--show-toplevel` names the tree git actually answers for, so it is
821
+ # compared against $1.
822
+ #
823
+ # Compared as a DIRECTORY (`-ef`, same device and inode), never as a string:
824
+ # $1 is the path `worktree list --porcelain` echoes and `--show-toplevel` is
825
+ # git's own resolved spelling, and the two legitimately differ for one and the
826
+ # same directory. A parent that was a plain directory at `worktree add` time
827
+ # and is a symlink now leaves the listed path non-canonical while git's answer
828
+ # is resolved (measured). And a worktree whose name is Unicode NFD-composed
829
+ # (`cafe` + U+0301) is listed PRECOMPOSED by the `core.precomposeunicode` git
830
+ # writes into every new repo on macOS, while `--show-toplevel` answers the
831
+ # on-disk NFD bytes — visually identical, byte-different, one directory
832
+ # (measured, git 2.50.1, Apple Git-155). `cd && pwd -P` canonicalises only
833
+ # the first: it echoes the spelling it was given, so a byte compare against it
834
+ # refused every healthy NFD worktree. `-ef` answers "same directory" for both
835
+ # and for any other spelling the filesystem aliases, and still refuses every
836
+ # redirect — each names a different directory. POSIX.1-2017's `test` does not
837
+ # define `-ef`; it is a ksh-derived extension bash, dash and BSD sh share, and
838
+ # POSIX.1-2024 adds it as a base primary. A `[` that cannot evaluate it
839
+ # returns 2 or more, and that is refused, never read as "not this one".
840
+ #
841
+ # $1 ITSELF a symlink needs one more question first, because `-ef` follows the
842
+ # link on both sides. A worktree directory replaced by a symlink to a
843
+ # different, healthy, registered worktree has git answering for the target and
844
+ # `-ef` agreeing, so the compare passes over a directory that is not the one
845
+ # registered — and `git worktree remove` then refuses it on its own
846
+ # back-pointer check, so a dry run promised what `--apply` cannot do (measured,
847
+ # git 2.50.1). So ask that back-pointer here: the admin dir git reaches
848
+ # through $1 holds a `gitdir` file naming the `.git` of the worktree it was
849
+ # registered for, and the listing derives each worktree's path from exactly
850
+ # that file — so for the listed path it reads `$1/.git` byte for byte, and
851
+ # through a link to ANOTHER worktree it names that one (measured: a link `A`
852
+ # to sibling `B` reaches `worktrees/B`, whose `gitdir` names `B/.git`). A
853
+ # string compare, because `-ef` is what cannot see this. Asked only of a link:
854
+ # a link standing in for the worktree's OWN renamed directory reaches its own
855
+ # admin dir and passes, and a plain directory never needs it — the NFD
856
+ # spelling `-ef` exists for would fail a string compare.
857
+ #
858
+ # `&& echo x` inside the substitution, then `%?x`: `$(...)` strips EVERY
859
+ # trailing newline, so a `core.worktree` naming a sibling directory called $1
860
+ # plus a newline byte — git accepts one as an ordinary path character — would
861
+ # otherwise name $1 itself and pass the redirect (measured). The sentinel
862
+ # leaves `$(...)` only git's own terminating newline to strip.
863
+ # `2>/dev/null` on that capture, for `wt_registry_root`'s reason; git's own
864
+ # words are fetched with a second call, only on the path that refuses.
865
+ #
866
+ # What this does NOT cover: shapes that swap which git DIR answers while the
867
+ # working tree stays $1 — a `.git` naming a sibling worktree's admin dir, or a
868
+ # foreign git dir whose `core.worktree` points back at $1. `--show-toplevel`
869
+ # answers $1 for both. A dirty check then reads $1's real files against the
870
+ # borrowed index, and `git worktree remove` refuses a `.git` that does not
871
+ # point back at its admin dir.
872
+ #
873
+ # Asked of the listing too, because the link check above needs $1 to BE the
874
+ # link, and under `worktree.useRelativePaths` it never is: git stores the
875
+ # back-pointer relative and resolves it, for the swapped entry, to the
876
+ # TARGET's directory, so the listing reports the swapped worktree at the
877
+ # target's path — two records naming one directory, the path the caller holds
878
+ # is the target's real directory, and no `-L` fires on it (measured, git
879
+ # 2.50.1: the sibling's live, clean worktree was then the one `reap --apply`
880
+ # removed). So when `$wt_list` holds more than one record for $1, which
881
+ # worktree stands there is unknown and $1 is refused. A caller that has read no
882
+ # listing (`$wt_list` empty or unset) skips this question. Counted in shell,
883
+ # line by line, so the question adds no external command whose failure would
884
+ # be a new way for a caller to refuse.
885
+ # shellcheck disable=SC2034
886
+ wt_linkage() {
887
+ wt_why=
888
+ wt_lk_n=0
889
+ if [ -n "${wt_list:-}" ]; then
890
+ # Whole records, one per line (`wt_listing` swapped any newline inside a
891
+ # path), so equality against `worktree $1` is the path compare, and a path
892
+ # that merely starts with $1 never counts. The heredoc keeps the loop in
893
+ # this shell.
894
+ while IFS= read -r wt_lk_l; do
895
+ if [ "$wt_lk_l" = "worktree $1" ]; then wt_lk_n=$((wt_lk_n + 1)); fi
896
+ done <<EOF
897
+ $wt_list
898
+ EOF
899
+ if [ "$wt_lk_n" -gt 1 ]; then
900
+ wt_why="the worktree listing names $1 for $wt_lk_n worktrees — a symbolic link standing in for another worktree's directory, so which one stands there is unknown"
901
+ return 1
902
+ fi
903
+ fi
904
+ if ! wt_lk_top=$(git -C "$1" rev-parse --show-toplevel 2>/dev/null && echo x); then
905
+ wt_lk_err=$(git -C "$1" rev-parse --show-toplevel 2>&1 >/dev/null) || :
906
+ wt_lk_err=$(printf '%s' "$wt_lk_err" | tr '\n' ' ') || wt_lk_err=
907
+ wt_why="cannot read the git repository at $1 — its .git linkage (the .git file or the gitdir it names) does not resolve${wt_lk_err:+: $wt_lk_err}"
908
+ return 1
909
+ fi
910
+ wt_lk_top=${wt_lk_top%?x}
911
+ if [ -L "$1" ]; then
912
+ if ! wt_lk_admin=$(git -C "$1" rev-parse --absolute-git-dir 2>/dev/null && echo x) ||
913
+ ! wt_lk_back=$(cat "${wt_lk_admin%?x}/gitdir" 2>/dev/null && echo x); then
914
+ wt_why="$1 is a symbolic link whose admin dir's gitdir back-pointer could not be read, so which worktree it stands for is unknown"
915
+ return 1
916
+ fi
917
+ # `cat` adds no newline of its own, so the sentinel alone comes off, then
918
+ # the one newline git writes after the path, if it is there.
919
+ wt_lk_back=${wt_lk_back%x}
920
+ wt_lk_back=${wt_lk_back%"
921
+ "}
922
+ if [ "${wt_lk_back%/.git}" != "$1" ]; then
923
+ wt_why="$1 is a symbolic link to another worktree's directory — its .git linkage reaches the admin dir registered for ${wt_lk_back%/.git}, not for $1"
924
+ return 1
925
+ fi
926
+ fi
927
+ # shellcheck disable=SC3013,SC2319 # -ef is a ksh-derived extension bash/dash/BSD sh share, base in POSIX.1-2024; the else's $? is deliberately the `[ -ef ]` test's own rc, read before anything else runs
928
+ if [ "$wt_lk_top" -ef "$1" ]; then return 0; else wt_lk_rc=$?; fi
929
+ if [ "$wt_lk_rc" -ge 2 ]; then
930
+ wt_why="could not compare $1 with $wt_lk_top, the working tree git answers for through it (test -ef exited $wt_lk_rc)"
931
+ return 1
932
+ fi
933
+ wt_why="$1's .git linkage does not point at $1 — git answers for the working tree at $wt_lk_top, not $1"
934
+ return 1
935
+ }
936
+
937
+ # Would removing the directory $1 delete the working directory $2? True when
938
+ # $2 is $1 or lies anywhere beneath it (a nested worktree). Removing a
939
+ # worktree a script stands in deletes that process's cwd, and every git call
940
+ # after it then dies with `fatal: Unable to read current working directory`
941
+ # (measured, git 2.50.1, Apple Git-155).
942
+ #
943
+ # Asked of the DIRECTORY, not the string: `-ef` of $2 and of each of its
944
+ # parents in turn. A byte-boundary prefix match missed the same directory
945
+ # spelled two ways — a symlinked parent, and the NFD name `wt_linkage`
946
+ # records — and a removal deleted the cwd it was standing in (measured). An
947
+ # empty $2 names no directory and matches nothing; the walk ends when no `/`
948
+ # is left to strip, so a $2 with no slash is compared once and never spins.
949
+ #
950
+ # A `[` that cannot evaluate `-ef` (2 or more) answers TRUE: fail closed.
951
+ # Nothing downstream of this guard re-checks the directory it protects, so
952
+ # reading that rc as "not this one" would disable the guard silently.
953
+ #
954
+ # Returns 0 or 1 only, and sets no `$wt_why`: the caller names the refusal,
955
+ # because only the caller knows whose cwd $2 is.
956
+ wt_holds_cwd() {
957
+ wt_hc_d=$2
958
+ while :; do
959
+ # shellcheck disable=SC3013,SC2319 # -ef as in wt_linkage; the else's $? is the `[ -ef ]` test's own rc, read before anything else runs, to fail closed on rc>=2
960
+ if [ "$wt_hc_d" -ef "$1" ]; then return 0; else wt_hc_rc=$?; fi
961
+ [ "$wt_hc_rc" -lt 2 ] || return 0
962
+ case "$wt_hc_d" in
963
+ */*) wt_hc_d=${wt_hc_d%/*} ;;
964
+ *) return 1 ;;
965
+ esac
966
+ done
967
+ }
968
+
969
+ # Which worktree holds branch $1 (the short name, `refs/heads/` added here)?
970
+ # Reads `$wt_list` as `wt_listing` (or `wt_counts`) last left it and sets
971
+ # `$wt_path` to the path of every record whose `branch` line names it — the
972
+ # main checkout included, one per line in listing order, empty when none.
973
+ #
974
+ # 1 with `$wt_why`, and `$wt_path` empty, whenever the answer is not one the
975
+ # listing established, because an empty `$wt_path` is "no worktree" to every
976
+ # caller and a delete follows it:
977
+ # - $1 empty: `refs/heads/` names no branch, and matching nothing would
978
+ # read as "no worktree";
979
+ # - `$wt_list` empty: a listing read always holds the main checkout, so an
980
+ # empty one was never read, or died before the caller got here;
981
+ # - awk could not finish the scan (a multibyte conversion failure, killed):
982
+ # its empty output is not an answer;
983
+ # - a holder's path lies inside the worktree registry itself. git resolves a
984
+ # `gitdir` file holding something other than an absolute path relative to
985
+ # the entry's admin dir, so a garbage `gitdir` lists the worktree at
986
+ # `<registry>/<entry>/<garbage>` — measured, git 2.50.1: `not a path` in
987
+ # `gitdir` lists `…/.git/worktrees/<entry>/not a path`, a path nothing is
988
+ # at, while the real checkout stands where it always did. Read as an
989
+ # absent worktree, its registration was cleared and its branch reaped,
990
+ # leaving the checkout orphaned. No `git worktree add` places a worktree
991
+ # inside the registry, so such a path is never where the checkout is.
992
+ #
993
+ # `-v b=`: awk processes escapes in a `-v` value, which is safe here only
994
+ # because a ref name cannot hold a backslash (`git check-ref-format` refuses
995
+ # one). The match is on the `branch` line, the path the whole rest of the
996
+ # `worktree` line — never `$2`, which a space in the path would truncate.
997
+ # shellcheck disable=SC2034
998
+ wt_find_branch() {
999
+ wt_path=
1000
+ wt_why=
1001
+ if [ -z "$1" ]; then
1002
+ wt_why="no branch name was given to look up, and an empty one matches no worktree"
1003
+ return 1
1004
+ fi
1005
+ if [ -z "$wt_list" ]; then
1006
+ wt_why="the worktree listing was not read, so whether $1 has a worktree is unknown"
1007
+ return 1
1008
+ fi
1009
+ if ! wt_fb_hit=$(printf '%s\n' "$wt_list" |
1010
+ awk -v b="refs/heads/$1" '/^worktree /{w=substr($0,10)} /^branch /&&$2==b{print w}'); then
1011
+ wt_why="could not scan the worktree listing for $1"
1012
+ return 1
1013
+ fi
1014
+ if [ -n "$wt_fb_hit" ]; then
1015
+ wt_registry_root || return 1
1016
+ # One holder per line: `wt_listing` swapped any newline INSIDE a path, so
1017
+ # every line here is one whole path. The heredoc keeps the loop in this
1018
+ # shell, so its `return` answers for the function.
1019
+ while IFS= read -r wt_fb_p; do
1020
+ case "$wt_fb_p" in
1021
+ "$wt_root"/*)
1022
+ wt_why="git lists $1's worktree at $wt_fb_p, inside the worktree registry $wt_root — its gitdir file names no worktree, so where the checkout stands is unknown"
1023
+ return 1
1024
+ ;;
1025
+ esac
1026
+ done <<EOF
1027
+ $wt_fb_hit
1028
+ EOF
1029
+ fi
1030
+ wt_path=$wt_fb_hit
1031
+ }
1032
+
1033
+ # Which release outcome does $1 hold — measured, never inferred from the rc of
1034
+ # the `git worktree remove` that preceded it? git drops the registration BEFORE
1035
+ # the directory and does not restore it when the directory delete fails, so
1036
+ # one call has three landing shapes and its exit code separates none of them.
1037
+ # All measured on git 2.50.1:
1038
+ #
1039
+ # dirty worktree rc 128, registration and directory kept
1040
+ # symlink standing in for the dir rc 255, registration CLEARED, path kept
1041
+ # unwritable .git/worktrees rc 255, registration and directory gone
1042
+ #
1043
+ # Writes `$wt_outcome`, one of CONTEXT.md's four Release outcome states:
1044
+ # `Unreleased` (registration and directory both present), `Deregistered`
1045
+ # (registration cleared, directory on disk), `Released` (both gone) or
1046
+ # `Indeterminate`, and `$wt_why` when Indeterminate for a reason git or awk
1047
+ # named. A registration that survived a directory that did not has no name of
1048
+ # its own and reports Indeterminate rather than being squeezed into
1049
+ # Unreleased. Returns 0 whatever the outcome — the answer is the variable.
1050
+ #
1051
+ # A FRESH listing, never the caller's `$wt_list`: that one was captured before
1052
+ # the mutation this measures. `$wt_list` is put back before returning, because
1053
+ # the caller's guards read their pre-mutation capture off it. Called as a bare
1054
+ # statement, never inside `$( )`: a subshell would take `$wt_why` with it.
1055
+ #
1056
+ # The registration is read with an `ENVIRON`-keyed awk, because a `-v`
1057
+ # assignment mangles a backslash in the path and the compare then falls to the
1058
+ # permissive answer. Its exit status is three-valued: 0 listed, 1 ran and found
1059
+ # nothing, 2 or more could not run — and that last one must not fold into "not
1060
+ # registered", which is what put a false Deregistered into a receipt for a
1061
+ # registration nothing established was cleared (measured). The directory is
1062
+ # `wt_occupied` composed with `gone`, the pairing `gone`'s own contract
1063
+ # prescribes for a caller that needs present and cannot-stat apart.
1064
+ # shellcheck disable=SC2034
1065
+ wt_outcome() {
1066
+ wt_why=
1067
+ wt_oc_prior=$wt_list
1068
+ if ! wt_listing; then
1069
+ wt_list=$wt_oc_prior
1070
+ wt_outcome=Indeterminate
1071
+ wt_why=$(printf '%s' "$wt_err" | tr '\n' ' ')
1072
+ return 0
1073
+ fi
1074
+ wt_oc_now=$wt_list
1075
+ wt_list=$wt_oc_prior
1076
+ if printf '%s\n' "$wt_oc_now" |
1077
+ P="$1" awk '/^worktree /{if (substr($0,10)==ENVIRON["P"]) f=1} END{exit !f}'; then
1078
+ wt_oc_rc=0
1079
+ else
1080
+ wt_oc_rc=$?
1081
+ fi
1082
+ if [ "$wt_oc_rc" -eq 0 ]; then
1083
+ if wt_occupied "$1"; then wt_outcome=Unreleased; else wt_outcome=Indeterminate; fi
1084
+ elif [ "$wt_oc_rc" -ne 1 ]; then
1085
+ wt_outcome=Indeterminate
1086
+ wt_why="could not tell whether $1 is still registered"
1087
+ elif wt_occupied "$1"; then
1088
+ wt_outcome=Deregistered
1089
+ elif gone "$1"; then
1090
+ wt_outcome=Released
1091
+ else
1092
+ wt_outcome=Indeterminate
1093
+ fi
1094
+ return 0
1095
+ }
@@ -27,7 +27,7 @@ Every precondition recomputed **inside** same command as delete:
27
27
  - **A worktree that checked the branch out while the delete ran is caught after it, and the branch is put back.** git has no lock that stops `git worktree add <p> <b>` between that holder check and the delete, and such an add writes only the new worktree's `HEAD` — the ref does not move, so the compare-and-swap succeeds and leaves the worktree on a branch that no longer exists (measured, git 2.50.1). So worktree.sh's `wt_recheck_delete` re-reads the listing right after the delete — and again, up to 20 times 0.1s apart, while an add in progress is listed `locked initializing` — and when a worktree holds the branch, or the wait runs out, recreates it at the tip with a create-only `git update-ref`. The branch is a KEEP naming the worktree or the entry, and its config section stays. A restore that fails is a KEEP naming the tip, git's error and the command that restores it by hand — or, when something recreated the branch since the delete, the commit it now sits at, left as it is, since the create-only restore never overwrites it. The branch's reflog does not come back.
28
28
  - **A cherry that cannot answer is a KEEP.** Capture git's output; never pipe git itself: `cmd | grep -q` takes grep's exit status, never cmd's, so a `git cherry` that dies (rc 128 — one unreadable loose object is enough) prints nothing, grep exits 1, and a dead probe reads identical to "nothing unmerged" (verified, git 2.50.1). Unanswerable probe authorizes no delete — same fail-closed shape as `worktree remove` below. Read the `+` anchored, too: the capture folds stderr in, so an unanchored match reads a `+` in a diagnostic as a commit. Pinned by a test.
29
29
  - **A worktree registry that cannot be read is a KEEP, for every `[gone]` branch in that pass.** The lookup decides whether the dirty, ignored-files and removal checks run at all; an unread registry reads identical to "no worktree", and `-D`, the delete then, needed no answer from the registry to delete a branch that has none — so failing open force-deleted merged branches blind. The holder check before the delete asks only whether a worktree holds the branch, never those other questions, so the lookup still fails closed on its own. The listing is re-read per branch, so one repo-level failure keeps every `[gone]` branch in the pass, each with git's own cause. Reap runs after every merge pass, so the next one retries: nothing is lost, nothing is reaped blind.
30
- - **A registry the listing does not match is a KEEP for the whole pass, not just one branch — if the fault is standing.** Eight real admin-directory faults leave `git worktree list` at rc 0 while the held entry loses its `branch` line (admin `HEAD` garbage, empty, missing or chmod 000) or leaves the listing (`gitdir` missing or chmod 000, admin dir chmod 000, `.git/worktrees` replaced by a file) — and git's own "used by worktree" `-D` refusal read the same admin state, so it deleted the branch a live worktree held (measured, git 2.50.1). The holder check that replaced that refusal reads the same listing and answers "not held" for seven of the eight (measured; "cannot tell" only for `HEAD` missing), so it is no backstop either. So before the lookup is trusted, linked entries listed are counted against entries under `<git-common-dir>/worktrees/` (inflight.sh's `count_registry`/`count_linked`, recount-before-refuse included), and any linked entry with a null `HEAD` and no `branch` line fails it too — the HEAD faults keep the counts equal. A dropped or nameless entry says nothing about which branch it held. The check re-reads the listing per branch, so a standing fault — one still there on every branch's own read — keeps every `[gone]` branch in the pass, the healthy ones included; a transient one, healed before the next branch's read, keeps only the branches whose listing it touched. Either way nothing is reaped blind, and the next pass retries once the registry reads consistent again.
30
+ - **A registry the listing does not match is a KEEP for the whole pass, not just one branch — if the fault is standing.** Eight real admin-directory faults leave `git worktree list` at rc 0 while the held entry loses its `branch` line (admin `HEAD` garbage, empty, missing or chmod 000) or leaves the listing (`gitdir` missing or chmod 000, admin dir chmod 000, `.git/worktrees` replaced by a file) — and git's own "used by worktree" `-D` refusal read the same admin state, so it deleted the branch a live worktree held (measured, git 2.50.1). The holder check that replaced that refusal reads the same listing and answers "not held" for seven of the eight (measured; "cannot tell" only for `HEAD` missing), so it is no backstop either. So before the lookup is trusted, linked entries listed are counted against entries under `<git-common-dir>/worktrees/` (worktree.sh's `wt_counts`, recount-before-refuse included), and any linked entry with a null `HEAD` and no `branch` line fails it too — the HEAD faults keep the counts equal. A dropped or nameless entry says nothing about which branch it held. The check re-reads the listing per branch, so a standing fault — one still there on every branch's own read — keeps every `[gone]` branch in the pass, the healthy ones included; a transient one, healed before the next branch's read, keeps only the branches whose listing it touched. Either way nothing is reaped blind, and the next pass retries once the registry reads consistent again.
31
31
  - **`worktree remove` without `--force`.** Refuses on modifications *and* untracked files, so double-covers dirty check. Refusal is finding to report, never something to force past.
32
32
 
33
33
  ## Why a second sweep, over worktrees rather than branches