Skip to content

Freephite and Graphite compatibility

stax uses the same metadata format as freephite (refs/branch-metadata/<branch>). Your existing stacks work immediately after install — no migration needed.

Instant migration

cargo install stax
# or: brew install cesarferreira/tap/stax

st status   # your existing stack appears immediately

Command mapping

freephite graphite stax
fp ss gt submit st stack submit · st ss · st s s
fp sr — st stack restack · st sr · st s r
fp bs gt branch submit st branch submit · st bs
fp us submit gt upstack submit st upstack submit
fp ds submit gt downstack submit st downstack submit
fp rs gt sync st sync · st rs
fp bc gt create st create · st bc
— gt create --insert st create --insert
— — st create --below
— gt get st get
fp bco gt checkout st checkout · st co
fp bu gt up st up · st bu
fp bd gt down st down · st bd
fp ls gt log st status · st ls
— gt modify st modify · st m
— gt edit st edit · st e
— gt upstack onto st upstack onto
fp restack gt restack st restack · st sr
— gt restack --upstack st upstack restack
— gt merge st merge
— — st cascade
— gt absorb st absorb
— — st undo · st redo
— gt split -f <path> st split --file <path>

st get mirrors the main Graphite gt get workflow without a central backend. With no argument, it syncs and restacks the current stack. With a branch or PR number, it fetches the trunk-to-target chain Stax can infer locally; if the target already exists locally, local upstack branches are synced by default, and --downstack opts out. --remote-upstack adds remote-only upstack PR branches discovered from open PR base/head metadata, best-effort from the forge.

New remote-only branches imported by st get are read-only stack bases: Stax can create and restack local branches on top of them, but submit skips pushing or updating the imported branch itself. Existing Stax-managed branches keep their ownership metadata when synced with st get. Existing local branches fast-forward when possible, or rebase local-only commits onto the fetched remote tip when histories diverge; --force is the explicit reset path. Branches checked out in another linked worktree are skipped. st freeze protects a tracked branch from restacks and sync history rewrites, including imported-tip refreshes and squash-merge cleanup rebases; st get --unfrozen <branch> clears that protection before syncing. Sync cleanup may delete an imported local support branch after it is merged or upstream-gone, but it will not push-delete the imported remote branch. If the imported branch already has a PR, stack-link comments still include and sync that PR, with labels relative to the PR being rendered.

Like Graphite's branch/upstack submit flow, st branch submit and st upstack submit can publish stale local branches without forcing an immediate local restack when the excluded parent is already synced to the remote. Stax does this without a central server by creating internal temporary refs for the push; local branch tips and stack metadata stay unchanged until you run st restack.

Short alias: st

stax also installs as st:

st ss   # same as st stack submit (or st s s)
st sr   # same as st stack restack (or st s r)
st rs   # same as st sync
st ls   # same as st status

Note: st s opens the stack subcommand group. Use st ls or st status for the status view.