/bl-sync - Git-Branchless Stack Sync

Category: Git Workflow

Sync your commit stack with the main branch. Fetches remote changes, rebases your stack, and handles post-merge cleanup.

Usage

/bl-sync [options]

Options

Option	Description
(none)	Sync with local main branch
--pull	Fetch remote + sync with updated main
--after-merge	Clean up after a PR was merged

Examples

# Sync with local main
/bl-sync

# Fetch and sync (most common)
/bl-sync --pull

# After your PR was merged on GitHub
/bl-sync --after-merge

Execution

This command delegates to the bl-sync-expert agent:

Task(subagent_type="git-workflow:bl-sync-expert",
     prompt="Execute sync: <options>")

Execution Instructions

1. Verify Prerequisites

   • Check git-branchless is installed
   • Check working directory is clean

2. Show Current State

   • Run git sl to display the stack
   • Show divergence from main if any

3. Execute Sync

   • For basic sync: git sync
   • For pull + sync: git sync --pull
   • For after-merge: git pull origin main then git move

4. Handle Conflicts

   • Show conflicting files
   • Guide through resolution
   • Continue with git rebase --continue

5. Remind About PRs

   • If branches exist, suggest git submit to update PRs

6. Confirm Result

   • Show final state with git sl

Interactive Flow

User: /bl-sync --pull

Agent: Fetching and syncing with main...

Fetching from origin...
remote: Counting objects: 5, done.

Current stack:
◆ old-main (main) old commit
┃
◯ abc123 feat: add User class
┃
● def456 feat: add validation

Syncing onto updated main...
[1/2] feat: add User class - ✓
[2/2] feat: add validation - ✓

◆ new-main (main) teammate's feature  ← Updated
┃
◯ xyz789 feat: add User class
┃
● uvw012 feat: add validation

Stack synced! 2 commits rebased onto updated main.

Note: Run `git submit` to update your PRs.

User: /bl-sync --after-merge

Agent: Cleaning up after PR merge...

Pulling latest main...
Already up to date with merge commit.

Current state:
◆ merge123 (main) Merge pull request #1
┃
✕ old-abc feat: add User class (merged)
┃
◯ def456 feat: add validation  ← Needs moving
┃
● ghi789 feat: add repository

Moving remaining commits onto merge...
git move -s def456 -d merge123

◆ merge123 (main) Merge pull request #1
┃
◯ new-def feat: add validation  ← Moved
┃
● new-ghi feat: add repository

Cleanup complete!

Next steps:
1. Recreate branch: git switch -c pr/validation
2. Push to remote: git submit -c @
3. Update PR base branch on GitHub

User: /bl-sync --pull
(with conflicts)

Agent: Fetching and syncing with main...

Syncing onto updated main...
[1/2] feat: add User class - ✓
[2/2] feat: add validation - CONFLICT

Conflict in: src/validation.py

<<<<<<< HEAD
def validate_email(email):
    # teammate's version
=======
def validate_email(email):
    # your version
>>>>>>> feat: add validation

To resolve:
1. Edit src/validation.py - choose correct version
2. git add src/validation.py
3. git rebase --continue

Or to abort: git rebase --abort

Error Handling

Error	Resolution
Dirty working directory	Prompt to commit or stash
No remote configured	Suggest git remote add origin <url>
Conflicts during sync	Guide through resolution
Lost commits	Use git undo -i to recover