Beagle SCM

POST: the tip-advancing commit-making verb (commit, ff, push)

POST makes a commit and/or advances a branch tip, in all combinations. A commit advances the WORKTREE only; the tracked branch tip moves only by an explicit ?branch — the two motions never couple (pins are the exception: the parent rewrites a sub's //wt/path#hash pin record on any base move, see Submodules). Always does fast-forward, refuses non-linear changes. The exact action sequence is defined by the shape of the URI:

1. Path: (unless Host is set) narrows the commit to a path/submodule.
2. Fragment: contains the commit message (if new commit is intended).
   • if any files are explicitly staged (PUT/DELETE), commits exactly those; a sub with put files commits first, the gitlink bubbles one level up (Submodules),
   • if none staged, auto-stages all changes to make the tree clean — dirty sub files bottom-up, then the resulting gitlinks (if none, errs out),
   • with active PATCH, may reuse the old commit message (rebase), then fragment can be empty (e.g. be post #).
3. Query: the target branch (remote if Host set) to advance to the wt base,
   • the ONLY way a branch tip moves; a commit alone never advances it,
   • (wt may untie from a branch if committed to other one).
4. Host: remote to send new commit(s) to.
5. Scheme: the protocol to use (ssh: be: etc).

CLI use

be post...
#msg                    — commit msg, refer back (merge parent)
#                       — reuse absorbed msg (empty fragment)
                        — (empty) bare: reuse absorbed msg (patch)
./path                  — narrow commit to path/submodule
./path#msg              — narrow commit to path, with msg
?branch                 — advance ?branch to the wt base hash
?..                     — advance parent branch to the wt hash
?                       — advance trunk to the wt hash
?other#msg              — commit onto ?other, untie wt from cur
ssh://host              — FF-push cur's tip to the remote (no commit)
ssh://host#msg          — commit, then FF-push to the remote
ssh://host/repo?branch  — push to a remote branch over the wire
be://host?branch        — push over beagle's keeper wire

RefLog/WTLog interaction

1. Reference Log: tracks branch-hash correspondence, mainly.
   • reads post,put,delete records to detect a branch tip,
   • writes a post record to set the new tip.
2. Worktree Log: tracks the state of the worktree:
   • reads put, delete records for the list of staged files,
   • reads patch records for the branches patched into the wt,
   • reads get/posts for the tracked branch and parent hash,
   • writes a post record, setting the base wt commit.

Merges, rebases and squashes

Summary of invocation patterns

Each arg shape maps to exactly one action; every tip motion is a fast-forward. A bare post advances the track, a #msg makes a commit, ?branch moves a ref, //wt and host targets advance other trees.

1. bare post advances the TRACK (the recentmost get record); it never commits.
   • tracking a branch: FF its ref to cur's tip; refuses in plain text when already at/past cur or unable to fast-forward,
   • tracking a worktree (a //X track row): get-style merge cur's tip into the target's files, then FF its base,
   • detached: refused, no track to advance; exception: an active patch reuses the absorbed message,
   • tracking a remote branch: FF-push cur's tip to that remote branch over the wire; no local commit.
2. post '#msg' makes a commit; the wt base moves, no ref ever does.
   • selective mode: any active put/delete in the mounted tree ⇒ commit exactly the staged set, staged subs first,
   • commit-all mode: nothing staged anywhere ⇒ auto-stage all changes, dirty subs bottom-up, the parent last,
   • a recursed sub's commit may spice the parent's message up with the sub path, like [dog] or [dog/abc] (case ./jab).
3. post ?branch: FF-move that ref to cur's tip, no commit, cur untouched; an absent branch is created; ? trunk, ?.. parent.
4. post //wt/path: merge the files into the target first (a conflict refuses BEFORE the base moves), then FF the target's base.
5. post ssh://host?br: FF-push cur's existing tip over the wire, no local commit; ssh://host#msg commits first, then pushes.