git.md - mozsearch

# Reorganizing a stack with git

Mechanics for `stack-reorganize` in a git checkout; `SKILL.md` has the

contract, the envision phase and the diagnosis. The commands assume a POSIX

shell (on Windows, Git Bash or the MozillaBuild shell; cmd.exe eats the `^`

in `HEAD^`).

git has no operation log, no recorded conflicts and no `absorb`, so: back the

branch up before the first rewrite and keep the backup until the series is

submitted, prefer constructions that are correct by construction over long

rebases that need resolving, and place part of a commit by rebuilding a tree

at the target position. The preconditions' "no conflicts in the original

commit series" is jj's; git records none, so a clean `git status` is the

whole check. Untracked files another occupant of the tree left are no

obstacle: leave them, and stage by path throughout the rebuild, never with

`git add -A`, which would sweep them into a leaf.

```

git branch backup-<name> <branch>      # any name; backup- is the convention

```

A construction built on a detached HEAD leaves the branch at the old tip, so

**finish by pointing the branch at the result**:

```

git branch -f <branch> HEAD

```

On the branch itself (`git reset --hard <base>` with it checked out) HEAD and

the branch move together and this step falls away, but the reset moves

whichever branch is checked out, so in a tree another agent can reach read

`git branch --show-current` immediately before it. Check

`git diff <backup> <branch>` after each rewrite of the whole branch and at the

last leaf of a construction, whose tree differs by design until then; for a

reorder it is **empty**. With a residue commit on top, `git diff <backup>

<branch>^` is the empty one, and `git diff <backup> <branch>` has to equal the

residue commit's own diff, so that it holds nothing the series should carry.

`git range-diff -s <base> <backup> <branch>` maps each old commit to its new

one; without `-s` it also prints the interdiff of every `!` pair, the form for

reading one pair. The markers:

- `=`: a commit that moved with its context lines unchanged.

- `!`: a moved commit whose context changed, a target that absorbed lines or

  lost an edit to a remainder now below it, or a narrowed commit the pairing

  still recognizes. The pair prints the old subject, so a reworded commit

  shows its old one.

- `<`: an absorbed or dropped commit, with no counterpart on the right.

- `>`: a new commit, with none on the left. A narrowed commit the pairing no

  longer recognizes shows twice, its old form as `<` and its new form as `>`

  on a line that starts `-:`, which a filter on a leading number drops.

The content check stays the empty `git diff`. `!` does not separate moved

context from real drift; whether a commit's changed lines are the same is one

line each side, with `-U0` so that the id hashes no context and no offsets,

only the lines themselves:

```

git show --format= -U0 <commit> | git patch-id --verbatim

```

The id covers the path headers, so a hunk re-targeted to another path, as a

drop's cascade does, never matches; there compare the changed lines themselves:

```

diff <(git show --format= -U0 <a> | grep '^[-+]' | grep -vE '^(\+\+\+|---) ' | sort) \

     <(git show --format= -U0 <b> | grep '^[-+]' | grep -vE '^(\+\+\+|---) ' | sort)

```

Empty means the same lines, in another file.

Inventory the range's renames and deletions before picking a construction;

they decide which ones are legal:

```

git diff --name-status <base> <tip>

```

**An empty diff is blind to misattribution.** A conflict resolved by taking one

side whole (`git checkout --theirs <file>`) can carry a change out of the

commit whose message explains it and into another one, with the net diff still

empty and the linter clean. After a rebase that conflicted, read each rewritten

commit's own diff and confirm it carries only the kind of change its subject

claims: pick a marker that identifies the change which belongs elsewhere - a

frontmatter key, a pref name, a function signature - and expect no hits in the

commits that don't own it:

```

git show --format= <commit> -- <paths> | grep -E '^[-+]<marker>'

```

## Measuring the churn

Evidence for both churn shapes, a dead intermediate and a commit rewriting

text from its own range:

```

bash <skill-dir>/scripts/git-churn.sh [--origins | --lines] [<carrier>] <base>..<tip> [-- <pathspec>...]

```

The script is `scripts/git-churn.sh` beside this reference,

`.claude/skills/stack-reorganize/scripts/git-churn.sh` from the repository root

when the skill loaded from the checkout; run it from the repository root, since

a pathspec is relative to the current directory. Run the copy the skill loaded

from, never one inside the range under repair. `<base>` is the commit below the

range; a prefix the owner keeps as it is moves it up, and measurement and

rebuild both start above it. The script prints the range's net total, the sum

of its commits' own totals, the gap between them, and each commit's total; a

range that keeps two copies of a directory in sync counts every line twice, so

pass one copy as the pathspec, and a hand resolution during a rebuild goes into

every copy.

The gap is the add-then-remove churn, but its **size is not a threshold**: a

hundred dead lines in a sixteen-hundred-line series reads as noise. Settle the

question by tracing what is dead: a symbol present in the individual commits but absent from the net diff

was built and torn out within the range.

**Trace each dead symbol's lifecycle**: its *birth* (the commit whose diff adds

its definition) and its *death* (the commit that removes it), e.g.

`git show <c> | grep -E '^[+-].*\bsymbol\b'` across the range. Where the churn

is prose there is no symbol to grep; `--origins` blames every line a commit

removes at that commit's parent and sums them by the commit that wrote them,

with the paths under each origin: removals from inside the range are churn to

absorb there, path by path, and removals of pre-range lines are the commit's

own work. It prints the summary table first, so one run serves both, and ends

with the files an in-range commit added that the tip lacks, the birth half of

a dead file's lifecycle. Blame credits a line to the last commit that touched

it and cannot tell a rewrite from an extension, so the in-range count is an

upper bound;

read each counted line. `--lines <carrier>` prints the ones that commit

removes under their origin, with the commit's own additions by path, where the

destination half of a move shows; without a carrier it prints every commit's,

tens of kilobytes on a dozen-commit range. The carrier's hunk in `git show

--format= <carrier> -- <path>` shows the block around each line and the `+`

line that replaced it, which tells an extension (own work) from a rewrite

(churn). The origin's own `git show` shows, in the line's `-`/`+` pair,

whether it rewrote the line or only touched it, which the block rule turns on.

Attribute by block: a block belongs to the commit that wrote most of it, a

blank line to the block it separates, and a line a commit only extended is

that commit's own work.

Then grep the tip for each dead symbol, `git grep -n '\bsymbol\b' <tip> --

<paths>`: a hit is a comment that still describes the dead model, and a rebuild

that reproduces the tip byte for byte makes some commit write that stale

comment at the symbol's birth. Collect the hits before building and fix them

in a residue commit on top, which the owner is free to drop; the `git diff

<backup> <branch>` check then takes its residue form. A dead data shape has no

one name: grep for its removed field names too, and read the doc comment of

every function whose signature the replacement changed, since a description

of the old shape can name no dead symbol at all.

The span from the first birth to the last death carries the dead model and is

often much smaller than the full range; resplitting only it captures most of

the churn win. Confirm the sub-range holds the bulk of the gap by measuring it

on its own. The per-commit column is each commit's size, not its churn; the

`--origins` table names the carriers from the remover's side, and the commit

that wrote the removed lines is the target. The gap and the origins count need

not agree: a churned line counts twice in the gap (its addition and its

removal) and once in the table, which counts removals only, and the gap also

carries diff alignment, so expect the gap on either side of twice the count

(scaffolding a move adds, a heading or blank lines the net diff never sees,

pushes it up; alignment pushes it either way) and reconcile them no further.

The gap does not add up across sub-ranges: two halves can each measure zero

while the whole range measures more, because a commit above rewrites lines a

commit below the split introduced. Measure the halves separately to find out

whether the residue sits inside a part of the range you are allowed to touch.

A small gap of either sign is alignment noise between the net diff and the

per-commit diffs, not a finding. An `R` entry in `git diff --name-status

<base> <tip>` means the full-range gap also carries rename alignment, which no

reorganization removes: the net diff pairs the renamed file with its new name

where the per-commit diffs see a rewrite plus a new file. Measure the range

without the renaming commit, on whichever side of it the churn lies; where the

renaming commit is itself a churn carrier, the `--origins` count stands in,

since blame at the parent sees the file under its old name and carries no

alignment. After a rebuild that keeps the rename, the gap is that alignment

plus twice the remaining in-range count, so read the `--origins` total rather

than the gap.

## Finding a forward reference

Take each cross-reference the range adds - a section heading, a symbol, a file

path, a flag - and confirm its definition exists at the commit that adds the

reference, not just at the tip. In prose the candidates are the backtick-quoted

headings, paths and hyphenated names and the double-quoted section titles the

commit adds; a path that illustrates rather than refers (an example inside a

sentence) is a hit to drop, not to check, and the pathspec keeps a code

file's string literals out:

```

git show --format= <commit> -- '*.md' | grep '^+' | grep -oE '`(#[^`]*|[^`]*\.(md|sh|mjs|js|css|json|yml|toml)|[a-z]+(-[a-z]+)+)`|"[A-Z][^"]{3,60}"' | sort -u

```

The pattern is a starting point; adapt its alternatives to the forms the

stack's prose uses.

In code, a call to a symbol that does not exist yet fails at that commit's

build or tests, but a comment naming one does not. Take the backticked

identifiers and `{@link}` targets in the added comment lines, and the

slash-qualified rule names that lint directives carry unquoted

(`stylelint-disable-next-line plugin/rule`):

```

git show --format= <commit> | grep -E '^\+\s*(//|/?\*)' | grep -oE '`#?[A-Za-z_][A-Za-z0-9_.]*(\(\))?`|\{@link [^}]+\}|\b[a-z-]+/[a-z]+(-[a-z]+)+\b' | sort -u

```

Grep the definition's form, not the bare name, which the reference itself and

a same-named section elsewhere also match; a method's is the name followed by

`(` at the start of a line, where a call has a `.` before the name:

```

git show <commit>:<file> | grep -c '^#* *<Heading>'

git grep -c -E '^\s*(static |async |get |set )*<method>\(' <commit> -- <paths>

```

A lint rule's definition is its registration (the plugin's rule index and the

linter's config); a file path's is the file itself, `git cat-file -e

<commit>:<path>`. Zero at that commit with a hit at the tip is a forward

reference. Reorder so the introducing commit comes first, or absorb the

reference into it. A reference to a name that exists at that depth is not a

forward reference, whatever a later commit does with the name. The mirror

defect, a comment at the tip naming a symbol the range removed, is what the

tip grep under Measuring the churn finds. That stale comment is the residue

commit's business, not this check's: a byte-exact rebuild makes some leaf

write it at the symbol's birth, so exclude the tip's stale symbols from this

grep and fix them on top.

## Splits

Follow the **`stack-split-commit`** skill and its `references/git.md`, which

also cover splitting a revision that is already in review and folding a fix

into the commit that needs it.

## Drops

The commands for `drop-superseded.md`, by its step.

1. **Bound the blast radius.** The two `git log` searches are in the shape

   reference itself.

2. **Drop it.**

```

   git branch backup-<name> <branch>          # skip if the backup above already exists

   git rebase --onto <commit>^ <commit> <branch>

```

3. **Resolve the cascade.** The rebase halts at each conflict. A faithful

   cascade makes the reverser's pick come out empty, and `git rebase` drops it

   with `dropping <sha> ... -- patch contents already upstream`. That message

   is the confirmation to look for, and git prints it on the `Rebasing (n/m)`

   progress line behind a carriage return, so read the rebase output raw or

   through `tr '\r' '\n'`; a filter that drops `Rebasing` lines drops the

   message with them. Once a delete/modify entry's change sits at the pre-move

   location, `git rm <path>` resolves the conflicted entry. A hunk written by

   hand during the cascade takes its text from the backup tip byte for byte,

   as under Absorbs, at the path where the text lives at the tip: the dropped

   file's own path does not exist there. `GIT_EDITOR=true git rebase

   --continue` after each: the continue opens an editor on the resolved

   commit's message, which a non-interactive shell cannot answer.

4. **Finish coupled changes at their source.** `git commit

   --fixup=<that-commit>`, then `GIT_SEQUENCE_EDITOR=true git rebase -i

   --autosquash <base>` with the base named explicitly (`--autosquash` without

   `-i` works from git 2.44).

5. **Validate.** `git diff <backup> <branch>` must be empty for a net-zero

   drop; `git reset --hard <backup>` returns to the input where it is not.

## Absorbs

Send a later commit's changes into the commits that introduced the text it

rewrites. Three constructions, in order of how much they leave to resolve.

**Where more than one commit is being absorbed, the absorbed commit is not the

tip, or a path it touches belongs to several targets, take the bottom-up

construction whatever the other paths do**; the others then cost one saved

diff and one cascade per commit. The path partition only

decides whether each bottom-up step is a whole-path restore or hand-written.

Whatever the construction, commit every rebuilt commit with

`git commit -C <original>`, then `git commit --amend -F <file>` where the body

changes: `git commit -m` or `-F` alone drops the author date and the

`Differential Revision` trailer with no warning.

**By fixup**, where each target's part is a whole file. Drop the absorbed

commit, re-add each target's part as a fixup of that target, and squash them

all in one rebase:

```

git rebase --onto <absorbed>^ <absorbed> <branch>     # the backup still holds it

git show <absorbed> -- <paths> | git apply --index    # once per target, then:

git commit --fixup=<target>

GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash <base>   # name the base explicitly; without -i it needs git 2.44

```

Where a target's part is only a subset of a file, split `git show <absorbed>`

into pieces by hand and apply each with `git apply --index <piece>`;

`git add -p` is interactive and unavailable here. A rework commit's hunks

seldom split that way: one hunk interleaves removals for one target with

additions for another, and a hunk computed against the tip's context fails to

apply at a target's depth when a kept commit in between touched the same

lines. When either happens, stop re-targeting hunks and take each block's

final text from the backup tip, the bottom-up construction below.

Abort on a conflict during the autosquash rather than resolving it, which

misattributes per above, and take the path rebuild instead.

**By path rebuild**, where the hunks partition by path. At each target commit,

take the paths it owns straight from the backup tip, so the content is correct

by construction:

```

git restore --source=<backup-tip> --staged --worktree -- <paths>

```

`git restore --source` runs in no-overlay mode by default: every tracked path

the pathspec matches and the source lacks is removed, so a directory pathspec

at a target commit also carries the deletions and renames that belong to

later commits, the misattribution above. Inventory them first, name files

rather than directories where the target must keep a path the backup tip

lacks, and stage by hand only what the pathspec did not name: a rename whose

`<new>` alone is named leaves `<old>` in place, so `git rm <old>` goes with

it. `git checkout <tree> -- <paths>` never removes a path and aborts on one

the tree lacks. Every restore in the bottom-up construction needs the same

inventory:

```

git diff --name-status <target> <backup-tip> -- <paths>

```

The backup tip carries every later commit's contribution too, so where a

commit above the target is being kept and touches the same paths, restoring

overshoots by its part. Where that commit's depth is free, place it below the

targets, so the top leaf is a whole-path restore and nothing overshoots;

otherwise take its part back off:

```

git show <later-commit> | git apply -R --index

```

That holds while the later commit's hunks still match. Where the later

commit's hunks no longer apply, do not lower the match context: a fuzzy apply

lands at false matches and reports success. Edit the file by hand from the tip

and judge it by its own diff and by the leaf above's, each of which must be

one concern alone, and by the per-commit gates.

**Bottom-up from the backup tip**, where one path belongs to several targets

and so cannot be restored whole at any one of them. Reset to the commit below

the range and build upward. Re-add a commit that moves unchanged with

`git cherry-pick <commit>`, which keeps its author, message and trailer where

`git show <commit> | git apply --index` fails on context that does not exist

yet. Try the original patch first for every leaf: `git show <commit> | git

apply --index --check` at the leaf's depth says whether it still applies, and

a commit the absorbed commit removed little from usually does, so only the

leaves that fail need hand-writing. A leaf found wrong after later leaves

exist takes a fixup of it (the fixup construction above), not a fresh

rebuild. Write the early commits that share the path by hand, taking each block's

text from the backup tip (`git show <backup-tip>:<path>`) byte for byte rather

than retyping it, so the later whole-path restore adds nothing back; for the

leaf directly below the tip, start from the tip's file and delete the lines the

top leaf owns, which keeps everything else byte-identical by construction. A

file assembled outside the tree goes in through git, the `hash-object` route

at the end of "Without touching the worktree" below. At each

later commit restore the paths whose final content is that commit's. Commit

every rebuilt commit, hand-written or restored, with `git commit -C <original>`

so it keeps the author, date, subject and `Differential Revision` trailer

(`git log -1 --format=%B <new> | grep '^Differential Revision:'` confirms the

trailer; `%(trailers)` does not parse that key); where the message must change

but the author and date stay, `git commit -C <original>` then `git commit

--amend -F <file>`. Nothing rebases, so no conflict arises and the net diff is

empty by construction.

**Without touching the worktree**, where the checkout is not yours to edit, the

same construction runs on a scratch index and loose objects, and the checkout

stays at the old tip until the end. Assemble each hand-written file outside

the tree from spans of the backup tip's blobs, then per commit:

```

idx=/tmp/reorg.idx                                     # a scratch index; the real one stays untouched

GIT_INDEX_FILE=$idx git read-tree <parent>             # the commit below in the new series

GIT_INDEX_FILE=$idx git update-index --add --cacheinfo <mode>,$(git hash-object -w <file>),<path>

GIT_INDEX_FILE=$idx git update-index --force-remove <path>

GIT_AUTHOR_NAME=<an> GIT_AUTHOR_EMAIL=<ae> GIT_AUTHOR_DATE=<ad> \

  git commit-tree $(GIT_INDEX_FILE=$idx git write-tree) -p <parent> -F <message-file>

```

`git log -1 --format='%an%n%ae%n%aD' <original>` supplies the author fields

and `git log -1 --format=%B <original>` the message, which is what `git commit

-C` copies; `git ls-tree <backup-tip> <path>` prints the mode; a whole-path

restore is `--cacheinfo <mode>,$(git rev-parse <backup-tip>:<path>),<path>`,

and a rename is a remove plus an add. `read-tree` and `write-tree` each take

seconds to tens of seconds on a mozilla-central-sized index, so budget about a

minute per commit. Finish with one `git reset --hard <last commit>` on the

checked-out branch, which `git branch -f` refuses to move. Where the checkout

is yours, keep the on-branch build; a hand-written file assembled in an

ignored directory is placed with `git hash-object -w`, `git update-index --add

--cacheinfo <mode>,<blob>,<path>` and `git checkout-index -f -- <path>`, which

writes it through git rather than through a shell edit a harness may record.

## Reorder (sink / hoist)

Inside a bottom-up rebuild a reorder is the order you build in. On its own,

move a commit to a new depth by reordering the rebase todo, matching on subject

text rather than hashes so the edit survives the rewriting:

```

GIT_SEQUENCE_EDITOR='<script that reorders the matching line>' git rebase -i <base>

```

A reorder is **content-preserving**, so `git diff <backup> HEAD` must be empty.

When the moved commit and the commits it crosses touched adjacent lines,

resolve the cascade by **strip-and-replay**. At the moved commit's new

position, take its full version (`git checkout <moved> -- <files>`) and *strip*

the additions that belong to the commits now replaying above it, leaving only

the moved commit's own additions on the base. Those commits then replay and

re-add their parts; resolve each re-addition as a **union**, ordering members

to match the final file's layout. Read that layout from `<backup>` (member and

case order) so the tree stays byte-identical.

Before reasoning about "the file", **map its path across the refs involved**: a

rename may live above the moved commit and replay on top, so the path at the

moved commit can differ from the path at the backup tip. A stray blank line

from a union separator shows up as a one-line final diff; fix it in the commit

that introduced it, not at the tip.

**Prove the moved commit stands alone.** When the point of the move is that

the commit is independently reviewable or landable, for instance because it is

being re-attributed to an earlier bug or phase, check it out in isolation,

build, and run the suite for the surface it touches. The empty net diff proves

only that the stack's final tree is unchanged, and a lint pass only syntax.

## Fold-resplit

Fold the range and resplit it by final concern, with the fold's end state as

the target. In git the fold needs no squash and the resplit is the bottom-up

construction under Absorbs, whole (`git commit -C <original>` for a leaf equal

to an input commit): the backup tip's tree is the end state, so

build on the branch (`git reset --hard <base>`, then write or restore each

leaf), take the last leaf with `git restore --source=<backup-tip> --staged

--worktree :/`, and cherry-pick back whatever sat above the range.

Fold-resplit is reserved for never-reviewed work, so `stack-split-commit`,

which adds the handling of a revision already in review, is not needed.

`fold-resplit.md` covers planning the leaves from the final state and building

a leaf no input commit held, reusing a prior split experiment, delegating a

long rebuild, and what each leaf's message and trailer become. Its commands:

an input commit's version of a file is `git show <commit>:<path>`; the

end-state's whole tree is `git restore --source=<end-state> --staged

--worktree :/`; a leaf that keeps an input commit's message and trailer is

`git commit -C <original>`.

## Verifying every commit, not just the tip

`mach lint` scores the worktree whichever commit you had in mind, so it cannot

check the per-commit invariant `# Goals` asks for from the tip. A bare

`./mach lint` scopes itself to the outgoing set against the default remote, so

at a detached checkout of a commit it lints the files that commit's prefix

changed, in that commit's tree; `./mach lint --outgoing <base>` names the base

instead of the remote.

Where the invariant is a whole-tree property git can read out of a commit - two

directories that have to stay in sync, a generated file that has to match its

source - no checkout is needed:

```

for c in $(git rev-list <base>..<branch>); do

  # skip commits where the path does not exist

  git cat-file -e $c:<dir-a> 2>/dev/null || continue

  git diff --quiet $c:<dir-a> $c:<dir-b> || echo "$c out of sync"

done

```

A tree diff covers the file set as well as the content; `git ls-tree -r

<commit> <path>` reads the set. A build, a linter or a test run needs a real

tree. On the branch, in a clean tree you own, `git rebase --exec '<command>'

<base>` runs the command at every commit in turn and stops at the first

failure (`warning: execution failed`); when every step passes nothing is

rewritten and the commits keep their ids. A failed step is consumed, so `git

rebase --continue` moves on without re-running it unless the rebase began with

`--reschedule-failed-exec`: either amend the commit it stopped at under that

flag and continue, or `git rebase --abort`, which returns to the branch, fix,

and rerun. The command can name the commit's own files, except at a commit

that changes the linter itself (a rule, its helpers, the config), whose own

files are the plugin's own sources, which the linter does not take as input,

so the per-file form passes there without linting anything; the invariant at

such a commit is that the whole tree lints clean under the changed rule:

```

git rebase --exec 'if git diff --quiet HEAD^ HEAD -- <linter-dir> <linter-config>; then ./mach lint -l <linter> $(git diff --name-only --diff-filter=d HEAD^ HEAD); else ./mach lint -l <linter> .; fi' <base>

```

The command stays on one line: `--exec` rejects a command containing a

newline, so a longer gate goes in a script file. `--diff-filter=d` keeps a path the commit deletes out of the list: `mach lint`

refuses a path that does not exist before it lints anything, and only filters

out a path of a type the linter does not read. Its summary line prints the

count under the same cross mark as a failure, so read the count, or let the

rebase read the exit status. Send the command's output to a file under

`artifacts/` (`{ ...; } >> artifacts/lint-<branch>.txt 2>&1` around the quoted

command) and read the summary lines there; the rebase acts on the exit status

either way. A message check run over the range scores the

kept commits' verbatim messages too; a complaint there is the owner's, not the

rebuild's.

A stack that changes a lint plugin has that plugin's own test suite and eslint

on its `.mjs` as per-commit gates too, run as the plugin's docs say (`npm`

lives under `~/.mozbuild/node/bin`, and a fresh worktree needs one `npm ci` in

the plugin directory first). Chain several gates in a script under

an ignored directory or outside the worktree and pass that to `--exec`, with

`set -o pipefail`

wherever a gate's output is filtered, since a pipe hides `npm run test`'s exit

status.

A build that must not disturb this tree runs in a detached worktree at the

commit instead. A fresh worktree has no objdir, so the first build there is a

full one; where every commit in the range has to build, prefer a checkout that

already has one.

Source code

Revision control

Copy as Markdown

Other Tools