feature sync

Keep your @local shadow branch in sync with the public branch after colleagues push new commits. Two modes are available depending on whether your shadow branch is personal or shared with teammates.

Usage

# Default: rebase the shadow branch onto the public branch
git shadow feature sync

# Shared shadow branch: merge instead of rebase (preserves history for push/pull workflows)
git shadow feature sync --merge

# Resume after manually resolving a [MEMORY] conflict
git shadow feature sync --continue

# Abort and return to the state before sync
git shadow feature sync --abort

What it does

  1. Validates you are on a shadow branch (ending with @local)
  2. Runs git rebase <public-branch> to replay your shadow commits on top of the latest public work
  3. For each conflicting commit:
    • Regular code commit → auto-resolved in favour of the public branch (--ours). If the commit becomes empty after resolution, it is silently dropped.
    • [MEMORY] commit → paused for manual resolution. Your local AI context files are never silently overwritten.
  4. Prints a success message once all commits are replayed.

Conflict handling

Code commits

Conflicts on regular commits are resolved automatically — the public branch version wins. You do not need to intervene.

🧠 Auto-resolving (code commit): feat(auth): update login route

[MEMORY] commits

Conflicts on [MEMORY] commits require manual resolution:

⚠️  Conflict on shadow commit: [MEMORY] add domain model notes
ℹ️  Conflicted files:
     docs/domain-model.md
ℹ️  Resolve conflicts manually, then run:
   git shadow feature sync --continue
ℹ️  To abort:
   git shadow feature sync --abort

Open the conflicted files, resolve them, stage the result, then continue:

# Resolve the conflicts in your editor, then:
git add docs/domain-model.md
git shadow feature sync --continue

Shared shadow branches (—merge mode)

By default, shadow branches are personal and local. But you can share a shadow branch with teammates by pushing it to the remote (see the FAQ). In that case, rebase rewrites history and would break your teammates’ local copies — use --merge instead.

--merge runs git merge <public-branch> with smart per-file conflict handling:

File in conflictHas local comments (///, ##, …)Result
Code fileNoAuto-resolved — public branch wins
Code fileYesPaused — manual resolution required
[MEMORY] file (notes, md…)—Never conflicts (doesn’t exist on public branch)

This ensures your local annotations are never silently overwritten, while pure code conflicts are handled automatically.

# Shared shadow branch workflow
git pull origin feature/login@local     # pull teammates' shadow commits
git pull origin feature/login           # update the public branch locally
git shadow feature sync --merge         # merge public into shadow
git push origin feature/login@local     # share the updated shadow branch

When a file with local comments conflicts, you’ll see:

⚠️  Conflict with local comments: src/auth.ts
⚠️  Some conflicted files contain local comments — manual resolution required.
ℹ️  Resolve each file above, stage it with 'git add', then run:
   git shadow feature sync --continue
ℹ️  To abort:
   git shadow feature sync --abort

Resolve each flagged file manually, keeping both the public code changes and your local comments, then:

git add src/auth.ts
git shadow feature sync --continue

When to use it

Run feature sync whenever the public branch has advanced since you last synced — typically after a colleague pushes, or before opening a merge request.

# Typical mid-feature workflow
git pull origin feature/login           # update public branch
git shadow feature sync                 # rebase shadow onto it (personal branch)
# or
git shadow feature sync --merge         # merge public into shadow (shared branch)