Overview
Watercooler provides several commands to ensure threads stay synchronized with their corresponding git branches. These commands help maintain clean branch pairing and audit thread-branch relationships.
Commands
check-branches
Comprehensive audit of branch pairing across the repository.
Usage
watercooler check-branches [options]
Options
Path to code repository. Defaults to current directory.
Include fully merged branches in the audit report
Examples
Audit all branches
watercooler check-branches
Branch Pairing Audit
====================
✓ feature-auth
Branch: feature-auth
Thread: feature-auth.md
Status: OPEN
Last updated: 2024-03-15T14:30:22Z
✗ api-redesign
Branch: api-redesign
Thread: NOT FOUND
Warning: Branch exists without corresponding thread
✗ orphan-thread
Thread: old-feature.md
Branch: NOT FOUND
Warning: Thread exists without corresponding branch
Summary:
Total branches: 3
Properly paired: 1
Missing threads: 1
Missing branches: 1
Include merged branches
watercooler check-branches --include-merged
Audit specific repository
watercooler check-branches --code-root ~/projects/myapp
check-branch
Validate branch pairing for a specific branch.
Usage
watercooler check-branch <branch> [options]
Arguments
Options
Path to code repository. Defaults to current directory.
Examples
Check specific branch
watercooler check-branch feature-auth
✓ Branch 'feature-auth' is properly paired
Thread: feature-auth.md
Status: OPEN
Ball: codex
Last updated: 2024-03-15T14:30:22Z
✗ Branch 'api-redesign' is not paired
Thread file not found: api-redesign.md
Suggestion: Run 'watercooler init-thread api-redesign'
Check branch in different repo
watercooler check-branch feature-auth --code-root ~/projects/myapp
merge-branch
Merge threads branch to main (git worktree operation).
Usage
watercooler merge-branch <branch> [options]
Arguments
Options
Path to code repository. Defaults to current directory.
Skip safety checks and force the merge
Examples
Merge threads branch
watercooler merge-branch feature-auth
Merging threads for branch: feature-auth
Safety checks:
✓ Branch exists
✓ Thread file exists
✓ No uncommitted changes in threads
✓ Thread status is CLOSED
Merging threads branch to main...
✓ Merge complete
Thread: feature-auth.md has been merged to main threads branch.
Force merge (skip checks)
watercooler merge-branch feature-auth --force
archive-branch
Close threads, merge to main, and delete branch.
Usage
watercooler archive-branch <branch> [options]
Arguments
Options
Path to code repository. Defaults to current directory.
Set OPEN threads to ABANDONED status instead of CLOSED
Skip confirmation prompts
Examples
Archive completed branch
watercooler archive-branch feature-auth
Archiving branch: feature-auth
Found threads:
- feature-auth.md (status: OPEN)
This will:
1. Set thread status to CLOSED
2. Merge threads to main
3. Delete branch 'feature-auth'
Proceed? [y/N]: y
Closing threads...
✓ feature-auth.md -> CLOSED
Merging threads to main...
✓ Merge complete
Deleting branch...
✓ Branch 'feature-auth' deleted
Archive complete.
Abandon branch without completion
watercooler archive-branch experimental-feature --abandon
Archiving branch: experimental-feature
Found threads:
- experimental-feature.md (status: OPEN)
This will:
1. Set thread status to ABANDONED
2. Merge threads to main
3. Delete branch 'experimental-feature'
Proceed? [y/N]: y
Abandoning threads...
✓ experimental-feature.md -> ABANDONED
Merging threads to main...
✓ Merge complete
Deleting branch...
✓ Branch 'experimental-feature' deleted
Archive complete.
Force archive (no prompts)
watercooler archive-branch old-feature --force
install-hooks
Install git hooks for automatic branch pairing validation.
Usage
watercooler install-hooks [options]
Options
Path to code repository. Defaults to current directory.
Git hooks directory. Defaults to .git/hooks.
Examples
Install hooks
watercooler install-hooks
Installing git hooks...
✓ Installed pre-commit hook
Validates thread pairing before commits
✓ Installed pre-push hook
Checks thread status before pushing
Hooks installed successfully.
Overwrite existing hooks
watercooler install-hooks --force
Installing git hooks...
⚠ Existing pre-commit hook backed up to .git/hooks/pre-commit.backup
✓ Installed pre-commit hook
⚠ Existing pre-push hook backed up to .git/hooks/pre-push.backup
✓ Installed pre-push hook
Hooks installed successfully.
Install in specific repository
watercooler install-hooks --code-root ~/projects/myapp
Installed Hooks
pre-commit hook
- Validates thread exists for current branch
- Warns if thread is missing
- Can be bypassed with
git commit --no-verify
pre-push hook
- Checks thread status before push
- Warns if pushing branch with OPEN threads
- Suggests closing or updating thread status
- Can be bypassed with
git push --no-verify
Workflows
New feature branch
# Create branch
git checkout -b feature-auth
# Initialize thread
watercooler init-thread feature-auth --title "OAuth Authentication"
# Work on feature...
# Verify pairing
watercooler check-branch feature-auth
Complete feature
# Close thread
watercooler say feature-auth \
--title "Feature complete" \
--body "PR merged." \
--type "Closure"
watercooler set-status feature-auth CLOSED
# Archive branch
watercooler archive-branch feature-auth
Audit repository health
# Check all branches
watercooler check-branches
# Fix issues
# - Create missing threads with init-thread
# - Archive orphan branches
# - Close stale threads
# Verify
watercooler check-branches
Best Practices
- Install hooks early: Run
install-hooks when setting up repository
- Regular audits: Run
check-branches periodically
- Clean branch lifecycle: Use
archive-branch to properly close work
- Document abandonment: Use
--abandon flag for incomplete work
- Verify before merge: Run
check-branch before merging PRs
