Beagle SCM

PATCH: absorb another branch's work into the worktree

PATCH absorbs commits from another branch into cur's worktree and records the absorbed sha(s) in .be/wtlog for the next POST to consume; it never commits on its own. The cycle is patch → test → post, one absorption per landing commit — so every commit that lands is a tested commit, never a chain of unverified work. PATCH is one verb in the Beagle Verbs vocabulary, and unlike GET it weave-merges theirs rather than overwriting the worktree.

• Does not commit, does not stage: the absorbed sha(s) are recorded in .be/wtlog, and the next POST turns them into a commit with a header; staging is PUT's job.
• PATCH picks the line and the origin record: ?ref absorbs the whole missing commit line, #hash cherry-picks one commit; plain patch records the ref as a merge parent, forceful patch! as a local foster.
• A dirty wt is fine: a 3-way WEAVE merges theirs against the wt's current bytes, so dirty files never cause a refusal.
• Conflicts are loud: a conflict hits stderr and exits non-zero, stopping an unattended patch && post before a bad commit.

Shapes and provenance

The URI slot picks WHAT is absorbed; the verb bang picks how the origin is recorded in the next commit. URI bangs are retired (the old ?br! whole-branch toggle is gone — ?ref always takes the whole missing line); the bang rides the verb only, and PATCH never carries a #message.

• ?<ref> (or bare patch = the tracked ref): absorb every missing commit of that line; the next POST records the ref as a non-first parent.
• patch! ?<ref>: same absorption, origin recorded as a foster header git does not understand — the fostered object is not propagated to other replicas, a local reference only.
• #<hash> cherry-pick, the special case: absorb the one named commit; recorded as picked, never a parent.
• A path-scoped shape records no origin at all (see the path-scoped section below).

Summary of invocation patterns

PATCH applies changes from a commit/branch, thus implementing merge, rebase, cherry pick.

1. patch comes in many forms:
   1. bare patch implies the tracked ref is the argument, so all the "miss" commits from that ref get applied and become "ptch"
   2. patch ?branch, patch ?tag, patch ?hash specify the commit line to patch in explicitly
   3. patch //worktree/path - worktree get (the actual tree base commit line)
   4. patch #hash cherry picks a particular commit, no parents, the hash is mentioned in a commit as "picked", not "parent"
   5. patch file:..., patch https:... and others imply the remote leg that updates remote refs, may download objects
2. patch modes
   1. whole tree (default)
   2. patch path/file?ref scoped to file/dir
3. commit history wise, the target ref can be
   1. behind, same as the current: nothing to do
   2. ahead, divergent: apply the missing
4. patch submodule recursion
   1. does not recur with --nosub
   2. by default: recurs; the state of the local tree is only used by weave merge; if a submodule tracks something else but the pin, applies patches anyway
5. merge/rebase
   1. default patch mentions the ref in the commit as non-first parent
   2. patch! forceful - mentions the the ref as foster (header not understood by git, so the object is not propagated to other replicas, for local reference only)

Ancestor-skip walk

An absorption replays only the commits cur doesn't already have — the missing set of the target line, computed by reachability from cur.

• A line absorption (?ref or bare patch) replays only commits not already reachable from cur via parent ∪ foster.
• picked headers are dedup-only and do not participate in reachability.
• A target behind or equal to cur has an empty missing set — nothing to do.

Merge base: full stack vs single commit

The merge base splits by shape: a line absorption weaves the whole missing stack against auto-LCA(cur, theirs), while a cherry weaves one commit against its own parent. The git-visible operation is picked by the origin record (parent vs foster), not by the base.

• Line ?ref uses auto-LCA(cur, theirs) and replays the full not-yet-reachable stack; with the parent header this is git's merge.
• Cherry #hash uses parent(theirs) as the base, weaving that one commit's diff — git's cherry-pick, recorded picked.
• patch!'s foster keeps the same weave but hides the link from git — the landed history reads linear, the rebase flavor.

Weave merge

PATCH never refuses on dirty files: it runs a 3-way WEAVE with the absorbed commit on the theirs side and the wt's current bytes on the ours side, so PATCH-on-PATCH composes by construction.

• The ours side is the wt's current bytes, including user edits and any prior output, so a prior absorption reads as an edit.
• Unresolvable conflicts are marked token-level with 4-char delimiters (<<<</>>>>), not git's 7-char line markers.
• git mergetool and existing UIs won't recognize the token-level markers — hand-edit, or enumerate via a diff:? view.

Path-scoped PATCH

A non-empty path slot scopes the absorption to those paths, but records no provenance — a partial absorption is not a faithful DAG commit.

• Path-scoped be patch file.c?feat lands theirs bytes for those paths only.
• A path-scoped row carries the path but no &theirs slot, so POST emits no provenance header and counts zero commits.
• Use a full (no-path) PATCH shape if you want POST to record provenance.

Reporting and status

Every PATCH prints a ULOG-style report — one line per applied commit and touched file, <verb> <status> <path-or-uri> — so the patch-test-post loop stays auditable.

• applied: the file was clean (baseline or stamped) and overlaid with theirs bytes, no merge needed.
• merged: the file had non-baseline bytes and theirs touched it, and WEAVE integrated both sides cleanly.
• mod: ours diverged from the merge base but theirs didn't touch this path, so the bytes are kept as-is (fork-relative).
• conflict: non-baseline bytes theirs touched but WEAVE couldn't resolve, leaving markers in the file and a non-zero exit.

Open questions

Two PATCH-side formats are still unsettled, both about how downstream tools read PATCH's output.

• The token-level 4-char conflict delimiters need a stable wire format for bro, graf-resolve, and a git mergetool adapter.
• A "partial picked" header naming <sha>:<path> for path-scoped forensics is a possible future extension.