Table of Contents

How to Sync Workspaces

Keep your workspace up to date with upstream changes from dependent work packages.

The Problem

You're working on WP02, and WP01 (which WP02 depends on) has changed. You need to update your workspace with the latest changes from upstream.

Prerequisites

  • Active workspace created via spec-kitty implement
  • spec-kitty 0.12.0+
  • Changes committed in the upstream workspace

Steps

1. Navigate to Your Workspace

cd .worktrees/001-my-feature-WP02/

2. Run Sync

spec-kitty sync workspace

You'll see output like:

Sync Workspace
├── ● Update workspace state
└── ● Rebase local changes on upstream

✓ Synced successfully
  Rebased 3 commits onto new upstream
  No conflicts detected

3. Verify the Sync

Check that upstream changes are now present:

git log --oneline -10

Conflict Handling

Sync may fail if conflicts are detected. You must resolve conflicts before proceeding.

Using --verbose for Details

Add --verbose to see detailed sync information:

spec-kitty sync workspace --verbose

Output includes:

  • Rebase operations performed
  • Any conflicts detected

Recovering with --repair

If your workspace is in a broken state (corrupted worktree, detached HEAD), use --repair:

spec-kitty sync workspace --repair

Warning: --repair may lose uncommitted changes. Commit your work first when possible.

This attempts to:

  1. Reset the workspace to a known good state
  2. Rebase your commits on top of the upstream base

Troubleshooting

"Working copy is not clean"

Commit or stash your changes before syncing:

git add . && git commit -m "WIP: save before sync"

"Cannot rebase: conflicts detected" (git only)

With git, you must resolve conflicts before sync completes:

# See conflicting files
git status

# Resolve conflicts in your editor
# Then mark as resolved
git add <resolved-files>
git rebase --continue

"Failed to update base: branch not found"

The base branch may have been deleted or renamed. Check available branches:

git branch -a

If the base branch is missing, you may need to recreate it or use --repair.

"Workspace not found"

Ensure you're in a valid workspace directory:

pwd
# Should be: /path/to/project/.worktrees/<feature>-WP##/

When to Sync

Sync your workspace:

  • Before starting new work: Get the latest changes first
  • After a dependent WP is merged: Incorporate those changes
  • Before code review: Ensure you have the latest base
  • When CI fails: Your workspace may be out of date

See Also

Edit this page