tomevault-io /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
Verify Prerequisites
- Check git-branchless is installed
- Check working directory is clean
Show Current State
- Run
git slto display the stack - Show divergence from main if any
- Run
Execute Sync
- For basic sync:
git sync - For pull + sync:
git sync --pull - For after-merge:
git pull origin mainthengit move
- For basic sync:
Handle Conflicts
- Show conflicting files
- Guide through resolution
- Continue with
git rebase --continue
Remind About PRs
- If branches exist, suggest
git submitto update PRs
- If branches exist, suggest
Confirm Result
- Show final state with
git sl
- Show final state with
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 |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.