Skip to content

Branch Commands

Manage schema branches for isolated development.

list

List all branches in the active database.

cinch branch list

Example Output

Branches in database 'main':
• main (active)
• feature.add-users
• feature.update-schema
• hotfix.fix-indexes

create

Create a new branch from the current branch.

cinch branch create BRANCH_NAME

Arguments

  • BRANCH_NAME - Name of the new branch

Options

  • --from BRANCH - Source branch (defaults to current branch)

Examples

# Create from current branch
cinch branch create feature.add-comments

✓ Created branch 'feature.add-comments' from 'main'
✓ Copied 3 tables and 5 tenants to new branch


# Create from specific branch
cinch branch create hotfix.fix-bug --from main

✓ Created branch 'hotfix.fix-bug' from 'main'

Notes

  • Copies all schema and tenants from source branch
  • Branch names can include periods and dashes for organization
  • Cannot create duplicate branch names

switch

Switch to a different branch.

cinch branch switch BRANCH_NAME

Arguments

  • BRANCH_NAME - Branch to switch to

Example

cinch branch switch feature.add-users

Notes

  • Updates active_branch in config
  • All subsequent commands use the new branch
  • Does not affect any uncommitted data

delete

Delete a branch.

cinch branch delete BRANCH_NAME

Arguments

  • BRANCH_NAME - Branch to delete

Options

  • --force - Skip confirmation

Example

# With confirmation
cinch branch delete feature.old-feature

# Without confirmation  
cinch branch delete feature.old-feature --force

Notes

  • Cannot delete the main branch
  • Cannot delete the active branch
  • Permanently removes all branch data

merge

Merge changes from one branch into another.

cinch branch merge SOURCE_BRANCH TARGET_BRANCH

Arguments

  • SOURCE_BRANCH - Branch with changes to merge
  • TARGET_BRANCH - Branch to merge into

Examples

# Merge feature into main
cinch branch merge feature.add-users main

# Merge while on target branch
cinch branch switch main
cinch branch merge feature.add-users .

Notes

  • Target branch must have all changes from source
  • Changes are applied to all tenants
  • Cannot merge if there are conflicts

merge-into-main

Shortcut to merge current branch into main.

cinch branch merge-into-main

Example

# On feature branch
cinch branch switch feature.add-users
# Make changes...
cinch branch merge-into-main

Equivalent to:

cinch branch merge feature.add-users main

changes

View changes made in a branch.

cinch branch changes [BRANCH_NAME]

Arguments

  • BRANCH_NAME - Branch to inspect (defaults to current)

Example Output

Changes in branch 'feature.add-users':
1. CREATE TABLE users (name TEXT, email TEXT)
2. CREATE VIEW active_users AS SELECT * FROM users WHERE active = true
3. ADD COLUMN avatar_url TEXT TO users

Common Workflows

Feature Development

# Create feature branch
cinch branch create feature.shopping-cart

# Make changes
cinch table create cart_items product_id:TEXT quantity:INTEGER
cinch table create orders user_id:TEXT total:REAL

# Review changes
cinch branch changes

# Merge to main
cinch branch merge-into-main

Hotfix Workflow

# Create hotfix from main
cinch branch create hotfix.fix-index --from main

# Make fix
cinch column add users last_login:TEXT

# Merge back quickly
cinch branch merge hotfix.fix-index main

Parallel Development

# Multiple features in parallel
cinch branch create feature.users
cinch branch create feature.products
cinch branch create feature.orders

# Work independently
cinch branch switch feature.users
cinch table create users name:TEXT

cinch branch switch feature.products  
cinch table create products name:TEXT price:REAL

# Merge when ready
cinch branch merge feature.users main
cinch branch merge feature.products main

Best Practices

  1. Branch Naming - Use descriptive names like feature., bugfix., hotfix.
  2. Small Changes - Keep branches focused on single features
  3. Regular Merges - Merge completed features promptly
  4. Review Changes - Always review before merging to main
  5. Clean Up - Delete merged branches to keep list manageable

Troubleshooting

"Branch already exists"

Problem: cinch branch create feature.users fails with "Branch already exists" Solution: Use cinch branch list to check existing branches, choose a different name

"Cannot merge: conflicts detected"

Problem: Merge fails with schema conflicts Solution: 1. Review changes: cinch branch changes feature.branch 2. Check target: cinch branch changes main 3. Resolve manually or recreate branch from updated main

"Cannot delete active branch"

Problem: Trying to delete the currently active branch Solution: Switch first: cinch branch switch main, then delete

Protection Rules

  • The main branch cannot be deleted
  • Direct changes to main are not allowed (merge only)
  • All schema changes must go through branches

Remote Operations

Branch commands work with remote connections:

Next Steps