Rebasing, Merging, and Syncing

Use spaces sync to keep your workspace up to date.

ℹ️

spaces sync updates dev-branches by rebasing them on their target upstream branch (or merging if configured). You do not need to manually run git fetch + git rebase before syncing. But you can if you want to.

Create a Workspace with a dev-branch

spaces co my-project fix-the-bug --new-branch=my-project
cd fix-the-bug

See Using spaces co for details on co.spaces.toml.

Develop Normally

Make changes, commit, and push on your dev branch.

Sync to Integrate with Upstream Changes

spaces sync

If you have local uncommitted changes, use:

spaces sync --stash

If you want to start development on another repo in the workspace, use:

spaces sync --new-branch=my-repo-in-workspace

Develop as Usual

spaces run //my-project:build
spaces run //:test

For detailed sync behavior and advanced options, see Repo Checkout and Sync.

Multiple Dev Branches

You can create dev branches in multiple repos within the same workspace. Pass multiple entries in new-branch:

spaces checkout-repo \
  --url=https://github.com/my-org/my-workspace \
  --rev=main \
  --new-branch=my-lib \
  --new-branch=my-app \
  --name=cross-cutting-change

Or in co.spaces.toml:

[cross-cutting.Repo]
url = "https://github.com/my-org/my-workspace"
rev = "main"
new-branch = ["my-lib", "my-app"]

Both my-lib and my-app are treated as dev branches and are updated during spaces sync (rebase by default, or merge if configured).

Promoting a Repo to a Dev Branch

Run spaces sync --dev-branch=<path to the repo in the workspace> to promote a repo to a dev branch. Use spaces sync --new-branch=<path to the repo in the workspace> if you haven’t already created a local branch.

After promotion, spaces sync will treat that repo as a dev-branch and include it in *dev-branch sync behavior (rebase by default, or merge if configured).

Adding Run Rules Using Spaces Co