/sync

Synchronize issues with git remote in a single operation.

Sync Steps

1. Export pending changes to JSONL
2. Commit changes to git
3. Pull from remote (with conflict resolution)
4. Import updated JSONL
5. Push local commits to remote

Wraps the entire git-based sync workflow for multi-device use.

Usage

• Basic sync: bd sync
• Preview: bd sync --dry-run
• Custom message: bd sync --message "Closed sprint issues"
• Pull only: bd sync --no-push
• Push only: bd sync --no-pull
• Flush only: bd sync --flush-only (export to JSONL without git operations)
• Import only: bd sync --import-only (import from JSONL without git operations)

Separate Branch Workflow

When using a separate sync branch (configured via sync.branch), additional commands are available:

• Check status: bd sync --status - Show diff between sync branch and main
• Merge to main: bd sync --merge - Merge sync branch back to main branch
• Preview merge: bd sync --merge --dry-run - Preview what would be merged

Merge Workflow

When working with a protected main branch and separate sync branch:

1. Beads commits go to the sync branch (e.g., beads-metadata)
2. Use bd sync --status to review pending changes
3. When ready, use bd sync --merge to merge back to main
4. After merge, run bd import to update the database
5. Run bd sync to push changes to remote

The merge command includes safety checks:

• Verifies you're not on the sync branch
• Checks for uncommitted changes in working tree
• Detects and reports merge conflicts with resolution steps
• Uses --no-ff to create a merge commit for clear history

Note

Most users should rely on the daemon's automatic sync (bd daemon --auto-commit --auto-push) instead of running manual sync. This command is useful for one-off syncs or when not using the daemon.