Skip to content

About

wt sync — rebase stacked worktree branches in dependency order

Resources

Stars

21 stars

Watchers

0 watching

Forks

Repository files navigation

wt-sync

Rebase stacked worktree branches in dependency order.

Works with any git worktrees — no special setup required. Can also be used as an external subcommand for worktrunk via wt sync.

How it works

wt sync detects the branch dependency tree from git's commit graph by merge-base analysis (one git rev-list dump of the worktree tips, cut off at their common ancestor), then rebases each branch onto its parent in topological order.

All rebases use --onto with a stored fork-point, so parent branches that have been rewritten (rebased, amended, or force-pushed) are handled correctly — no duplicate commits or spurious conflicts.

Persisted state

Two files are stored in .git/wt/ (shared across all worktrees):

  • stack — the dependency tree in git-machete compatible format, used for parent tracking and integration detection.
  • stack-forkpoints — each branch's parent SHA at last sync, used as the --onto base for the next rebase.

Both files are auto-created and updated on every sync.

Install

cargo install worktrunk-sync

The binary is named wt-sync and can be run directly. If worktrunk is installed, it also works as wt sync via external subcommand dispatch.

Usage

wt-sync -upP         # day to day: pull main, rebase, push, prune merged
wt-sync              # sync the current stack (default)
wt-sync --all        # sync all stacks
wt-sync -nv          # preview the plan with git commands
wt-sync --pull       # fetch, fast-forward main, then sync
wt-sync --push-only  # push the current stack without rebasing

# Or via worktrunk:
wt sync
wt sync --all

Day to day

Most of the time you want one command, run from any worktree in the stack you're working on:

wt sync -upP    # same as: wt sync --pull --push --prune

It fetches, fast-forwards main to origin/main, rebases the current stack onto it, pushes the rebased branches, and removes worktrees whose branches have been merged (so after a PR merges on GitHub, its worktree goes away and the branches above it move onto main).

Add -nv to see what it would do first, and --all to do it for every stack instead of just the current one:

wt sync -upP -nv     # preview, with the git commands
wt sync -upP --all   # every stack

Drop the flags you don't want: plain wt sync only rebases locally, without -P merged worktrees are kept, and without -p nothing is pushed. Nothing is on by default, because pulling, pushing and pruning all change things outside your current branch. If you type -upP all the time, a worktrunk alias saves the keystrokes:

# ~/.config/worktrunk/config.toml
[aliases]
ss = "wt-sync -upP"

Fetch vs pull

--fetch only updates the remote-tracking refs (origin/main); branches are still rebased onto your local main. That is enough to detect branches merged on the remote, but if your local main is behind, the stack ends up rebased onto a stale base. wt sync warns about that:

⚠ main is 3 commits behind origin/main; run with --pull to update it

--pull (-u) mirrors git pull --ff-only for the root: it fetches, then fast-forwards main to its upstream before the stack is rebased, so the rebase lands on what the remote actually has. Stacked branches are never touched by this step. The root is only moved when that's safe: its worktree must be clean with no rebase or merge in progress. A root that has diverged from its upstream, has no upstream, or sits in a dirty worktree is left alone with a warning, and the sync continues as it would have without --pull. In --dry-run mode no fetch happens, so the preview is based on the remote-tracking refs you already have.

Push only

wt sync --push-only        # current stack
wt sync --push-only --all  # every stack

Pushes each branch in the selected scope as-is (git push --force-with-lease), in dependency order, without fetching or rebasing. Branches without an upstream are skipped and listed, just like with --push; add --publish to push them too. Worktrees don't need to be clean, and the stack/fork-point files are left untouched. Exits non-zero if any push fails. Run from the default branch's worktree, the "current stack" is every stack, so all branches are pushed. Combine with -nv to preview the push commands. Cannot be combined with --push, --fetch or --prune.

Publishing new branches

--push only pushes branches that already have an upstream, so a branch you never pushed stays local, and the output lists it ("Not pushing b, c: they have no upstream yet"). To push those too:

wt sync --publish     # rebase, then push, and publish branches with no upstream
wt sync -n --publish  # see where each new branch would go

--publish implies --push (or combine it with --push-only). Each new branch is pushed with git push -u, which sets its upstream, to the remote its nearest pushed parent uses. If none of the branches it sits on is pushed, it goes to remote.pushDefault, then origin, then the only remote. The root branch is never used to pick the remote, because in a fork main usually tracks the original repo, and your branches don't belong there.

gh-stack

gh-stack (gh stack) manages stacked PRs on GitHub: it opens one PR per branch, links them as a stack, and merges them together. wt sync keeps worktrees rebased without any bookkeeping. They work well together: use wt sync to keep the worktrees up to date, and gh stack submit / gh stack merge for the PR side.

If you registered branches with gh stack init or gh stack add, wt sync uses the order you declared for those branches instead of inferring it, and marks them with (gh-stack) in the dry-run tree. Other branches are still inferred. Branches whose PR is merged are skipped, so their children move down to the next branch in the stack.

wt sync only reads gh-stack's catalog (.git/gh-stack). It never writes it and never runs gh stack sync, push or submit. It also refuses to run while a gh stack rebase or modify is paused, since those branches are mid-rewrite. If gh-stack isn't installed, nothing changes. Pass --no-gh-stack to ignore gh-stack and infer every parent.

To go the other way and hand stacks wt-sync worked out to gh-stack, so you can open them as stacked PRs with gh stack submit:

wt sync --gh-stack-init --all       # print a `gh stack init` command per stack
wt sync --gh-stack-init=run --all   # run them

This only registers the stacks; nothing is rebased or pushed. gh-stack stacks are a straight line, so a stack where a branch has several branches on top of it is skipped with a warning, and so is a stack with a branch that is already in gh-stack. The default is to print, because running gh stack init writes gh-stack's catalog and lets gh-stack set up the repo the way it wants.

Flags

Flag Short Description
--stack -s Sync only the current stack (default)
--all -a Sync all stacks
--fetch -f Fetch from remote before syncing
--pull -u Fetch, then fast-forward the root branch to its upstream (implies --fetch)
--push -p Push rebased branches after syncing
--push-only Push the stack as-is, without fetching or rebasing
--publish Also push branches with no upstream yet (git push -u), see Publishing new branches
--prune -P Remove integrated worktrees after syncing
--force -F Force removal of dirty integrated worktrees (with --prune)
--verbose -v Show git commands that would be executed
--dry-run -n Preview the sync plan without executing
--no-gh-stack Ignore stacks declared in gh-stack
--gh-stack-init[=run] Print (or run) gh stack init for each stack instead of syncing, see gh-stack

Example

$ wt-sync -nv
Dependency tree:
main
├── feature-a
│   └── feature-b
└── feature-c

Planned operations:
  rebase feature-a onto main
    $ git rebase --onto main abc1234 feature-a
  rebase feature-b onto feature-a
    $ git rebase --onto feature-a def5678 feature-b
  rebase feature-c onto main
    $ git rebase --onto main abc1234 feature-c

Key behaviors

  • Zero configuration — dependencies are inferred from git history
  • Fork-point tracking — stores the parent SHA at each sync so --onto rebases work correctly even after the parent is rewritten
  • Integrated branch detection — branches merged into their parent (or into the default branch) are detected; their children are reparented automatically
  • Conflict handling — before rebasing a branch, git merge-tree checks whether it would conflict, and a branch with merge commits of its own (an integration branch, say) is never rebased, since a rebase would flatten the merges. Either way the branch and everything stacked on it are skipped with a warning (and not pushed), their worktrees are left untouched, and the rest of the sync goes on. A conflict the check didn't predict stops the sync with instructions to resolve; fork-points for already-rebased branches are saved so re-running wt sync picks up where it left off
  • Non-zero exit on conflict — when a branch was skipped or a rebase stopped, so wt sync && wt sync --push won't silently push past a conflict
  • From the default branch, every stack — run from main's worktree, the current stack is all of them, and wt sync says so; run from a stack's worktree to sync only that stack

Requirements

  • Git with worktrees (git worktree add)
  • worktrunk >= 0.35 (runtime dependency for repository utilities)

Development

Build & test

cargo build
cargo test
cargo clippy --all-targets -- -D warnings

Pre-commit hooks

Install pre-commit and enable hooks:

pip install pre-commit
pre-commit install

Hooks run automatically on each commit (rustfmt, clippy, typos, trailing whitespace, etc.). To run manually:

pre-commit run --all-files

Releasing a new version

  1. Bump the version in Cargo.toml
  2. Commit and tag:
    git add Cargo.toml Cargo.lock
    git commit -m "release: v0.2.0"
    git tag v0.2.0
    git push && git push --tags
  3. The release workflow will automatically:
    • Build and test
    • Publish to crates.io
    • Create a GitHub release with auto-generated notes

License

MIT

About

wt sync — rebase stacked worktree branches in dependency order

Resources

Stars

21 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages