beads/commands/sync.md at 7ad2bbbcde550f69038e355db5d5478268cf865b

Files

Steve Yegge dfc8e48b57 Add git hooks check to bd doctor

- Adds checkGitHooks() function to verify recommended hooks are installed
- Checks for pre-commit, post-merge, and pre-push hooks
- Warns if hooks are missing with install instructions
- Shows up early in diagnostics (even if .beads/ missing)
- Includes comprehensive test coverage
- Filed bd-6049 for broken --json flag

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-02 17:09:39 -08:00

1.9 KiB

Raw Blame History

description: Synchronize issues with git remote argument-hint: [--dry-run] [--message] [--status] [--merge]

Synchronize issues with git remote in a single operation.

Sync Steps

Export pending changes to JSONL
Commit changes to git
Pull from remote (with conflict resolution)
Import updated JSONL
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:

Beads commits go to the sync branch (e.g., beads-metadata)
Use bd sync --status to review pending changes
When ready, use bd sync --merge to merge back to main
After merge, run bd import to update the database
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.

1.9 KiB Raw Blame History