403 lines
7.9 KiB
Markdown
403 lines
7.9 KiB
Markdown
# GitButler Examples
|
|
|
|
Real-world patterns and workflows for virtual branches, multi-agent collaboration, and post-hoc organization.
|
|
|
|
---
|
|
|
|
## Basic Workflows
|
|
|
|
### First Virtual Branch
|
|
|
|
```bash
|
|
# Initialize (one time)
|
|
cd /path/to/repo
|
|
but setup
|
|
|
|
# Check state
|
|
but status
|
|
# ● 0c60c71 (common base) [origin/main]
|
|
|
|
# Create branch
|
|
but branch new feature-user-auth
|
|
|
|
# Make changes
|
|
echo "export function authenticate()" > src/auth.ts
|
|
echo "test('authenticates user')" > src/auth.test.ts
|
|
|
|
# Check status for file IDs
|
|
but status
|
|
# ╭┄00 [Unassigned Changes]
|
|
# │ m6 A src/auth.ts
|
|
# │ p9 A src/auth.test.ts
|
|
|
|
# Assign and commit
|
|
but rub m6 feature-user-auth
|
|
but rub p9 feature-user-auth
|
|
but commit feature-user-auth -m "feat: add user authentication"
|
|
```
|
|
|
|
### Context Switching (No Checkout!)
|
|
|
|
```bash
|
|
# Working on feature when bug reported
|
|
but branch new feature-dashboard
|
|
echo "Dashboard code" > dashboard.ts
|
|
but rub <id> feature-dashboard
|
|
|
|
# Bug reported - switch context immediately (no checkout!)
|
|
but branch new bugfix-login-timeout
|
|
echo "Fix timeout" > login.ts
|
|
but rub <id> bugfix-login-timeout
|
|
|
|
# Both exist in same workspace
|
|
but status # Shows both branches
|
|
|
|
# Commit bugfix first (urgent)
|
|
but commit bugfix-login-timeout -m "fix: resolve login timeout"
|
|
|
|
# Continue feature work
|
|
but commit feature-dashboard -m "feat: add dashboard"
|
|
```
|
|
|
|
---
|
|
|
|
## Reorganizing Work
|
|
|
|
### Moving Commits Between Branches
|
|
|
|
```bash
|
|
# Oops, committed to wrong branch!
|
|
but status
|
|
# Shows def5678 "feat: add new feature" on bugfix-branch
|
|
|
|
# Create correct branch
|
|
but branch new feature-new-capability
|
|
|
|
# Move the commit
|
|
but rub def5678 feature-new-capability
|
|
|
|
# Commit moved!
|
|
but status
|
|
```
|
|
|
|
### Squashing Commits
|
|
|
|
```bash
|
|
# Too many small commits on feature-branch
|
|
# Squash using explicit command
|
|
but squash feature-branch
|
|
```
|
|
|
|
### Post-Hoc File Assignment
|
|
|
|
```bash
|
|
# Made changes without branches
|
|
echo "Auth code" > auth.ts
|
|
echo "API code" > api.ts
|
|
echo "Docs" > README.md
|
|
|
|
but status
|
|
# Shows all files in Unassigned Changes
|
|
|
|
# Create branches and organize
|
|
but branch new feature-auth
|
|
but branch new feature-api
|
|
but branch new docs-update
|
|
|
|
# Assign to respective branches
|
|
but rub m6 feature-auth
|
|
but rub p9 feature-api
|
|
but rub i3 docs-update
|
|
|
|
# Commit each
|
|
but commit feature-auth -m "feat: add authentication"
|
|
but commit feature-api -m "feat: add API endpoints"
|
|
but commit docs-update -m "docs: update readme"
|
|
```
|
|
|
|
---
|
|
|
|
## Multi-Agent Patterns
|
|
|
|
### Parallel Feature Development
|
|
|
|
```bash
|
|
# Agent 1 (Claude)
|
|
but branch new claude-feature-auth
|
|
echo "Auth implementation" > src/auth.ts
|
|
but rub <id> claude-feature-auth
|
|
but commit claude-feature-auth -m "feat: add authentication"
|
|
|
|
# Agent 2 (Droid) - simultaneously, same workspace!
|
|
but branch new droid-feature-api
|
|
echo "API implementation" > src/api.ts
|
|
but rub <id> droid-feature-api
|
|
but commit droid-feature-api -m "feat: add API endpoints"
|
|
|
|
# Zero conflicts, zero coordination overhead
|
|
```
|
|
|
|
### Sequential Handoffs
|
|
|
|
```bash
|
|
# Agent A: Initial implementation
|
|
but branch new feature-user-management
|
|
echo "Initial user code" > user.ts
|
|
but rub <id> feature-user-management
|
|
but commit feature-user-management -m "feat: initial user management"
|
|
|
|
# Agent A hands off to Agent B
|
|
but branch new feature-user-management-tests --anchor feature-user-management
|
|
|
|
# Agent B: Adds tests
|
|
echo "Tests for user management" > user.test.ts
|
|
but rub <id> feature-user-management-tests
|
|
but commit feature-user-management-tests -m "test: add user management tests"
|
|
```
|
|
|
|
### Cross-Agent Commit Transfer
|
|
|
|
```bash
|
|
# Agent A finishes work
|
|
but branch new agent-a-feature
|
|
but commit agent-a-feature -m "feat: implementation complete"
|
|
|
|
# Agent B creates their branch
|
|
but branch new agent-b-continuation
|
|
|
|
# Transfer commit from A to B
|
|
but rub abc1234 agent-b-continuation
|
|
|
|
# Agent B continues
|
|
echo "More work" >> feature.ts
|
|
but commit agent-b-continuation -m "feat: continue implementation"
|
|
```
|
|
|
|
---
|
|
|
|
## Stack Management
|
|
|
|
### Creating a Linear Stack
|
|
|
|
```bash
|
|
# Base refactoring
|
|
but branch new refactor-database
|
|
echo "Refactor database layer" > db-refactor.ts
|
|
but rub <id> refactor-database
|
|
but commit refactor-database -m "refactor: restructure database"
|
|
|
|
# Build on refactoring
|
|
but branch new feature-new-model --anchor refactor-database
|
|
echo "New data model" > model.ts
|
|
but rub <id> feature-new-model
|
|
but commit feature-new-model -m "feat: add new data model"
|
|
|
|
# Add tests on top
|
|
but branch new test-new-model --anchor feature-new-model
|
|
echo "Model tests" > model.test.ts
|
|
but rub <id> test-new-model
|
|
but commit test-new-model -m "test: comprehensive model tests"
|
|
|
|
# Visualize stack
|
|
but status
|
|
```
|
|
|
|
### Submit Stack as PRs
|
|
|
|
```bash
|
|
# Using but CLI (preferred)
|
|
but push refactor-database
|
|
but pr new refactor-database
|
|
|
|
but push feature-new-model
|
|
but pr new feature-new-model
|
|
|
|
but push test-new-model
|
|
but pr new test-new-model
|
|
```
|
|
|
|
```bash
|
|
# Alternative: using git + gh directly
|
|
git push origin refactor-database
|
|
gh pr create --title "refactor: database layer" --base main
|
|
|
|
git push origin feature-new-model
|
|
gh pr create --title "feat: new data model" --base refactor-database
|
|
|
|
git push origin test-new-model
|
|
gh pr create --title "test: model tests" --base feature-new-model
|
|
```
|
|
|
|
---
|
|
|
|
## Emergency Recovery
|
|
|
|
### Recover Deleted Branch
|
|
|
|
```bash
|
|
# Oops, deleted wrong branch
|
|
but branch delete important-feature --force
|
|
|
|
# Check oplog
|
|
but oplog
|
|
|
|
# Undo deletion
|
|
but undo
|
|
|
|
# Verify recovery
|
|
but status # Branch recovered!
|
|
```
|
|
|
|
### Recover from Bad Reorganization
|
|
|
|
```bash
|
|
# Snapshot before risky operations
|
|
but oplog snapshot --message "Before reorganizing commits"
|
|
|
|
# Attempt reorganization
|
|
but rub <commit1> <branch1>
|
|
but rub <commit2> <branch2>
|
|
|
|
# Result is a mess - restore to snapshot
|
|
snapshot_id=$(but oplog | grep "Before reorganizing" | awk '{print $1}')
|
|
but oplog restore $snapshot_id
|
|
|
|
# Back to pre-reorganization state!
|
|
```
|
|
|
|
### Recover from Mixed Git/But Commands
|
|
|
|
```bash
|
|
# Made changes on virtual branch
|
|
but branch new my-feature
|
|
echo "changes" > file.ts
|
|
|
|
# Accidentally used git
|
|
git add file.ts
|
|
git commit -m "oops" # WRONG!
|
|
|
|
# Recovery
|
|
but pull
|
|
|
|
# If still broken, reinitialize
|
|
but oplog snapshot --message "Before recovery"
|
|
but setup
|
|
```
|
|
|
|
---
|
|
|
|
## New in 0.19.0
|
|
|
|
### Selective Commit with `--changes`
|
|
|
|
```bash
|
|
# Check status for file/hunk IDs
|
|
but status
|
|
# ╭┄00 [Unassigned Changes]
|
|
# │ m6 A src/auth.ts
|
|
# │ p9 A src/api.ts
|
|
# │ i3 M README.md
|
|
|
|
# Commit only specific files by ID
|
|
but commit feature-auth -p m6,i3 -m "feat: add auth and update docs"
|
|
|
|
# p9 remains uncommitted
|
|
```
|
|
|
|
### Conflict Resolution with `but resolve`
|
|
|
|
```bash
|
|
# After pulling, a commit has conflicts
|
|
but pull
|
|
but status
|
|
# Shows conflicted commit with ⚠️ marker
|
|
|
|
# Enter resolution mode
|
|
but resolve abc1234
|
|
|
|
# Fix conflict markers in your editor
|
|
# Check what's left
|
|
but resolve status
|
|
|
|
# Finalize
|
|
but resolve finish
|
|
```
|
|
|
|
### Squashing with Ranges
|
|
|
|
```bash
|
|
# Squash all commits in a branch
|
|
but squash feature-branch
|
|
|
|
# Squash specific commits
|
|
but squash abc1234 def5678
|
|
|
|
# Squash a range
|
|
but squash abc1234..ghi9012
|
|
```
|
|
|
|
### Absorb with Preview
|
|
|
|
```bash
|
|
# Preview where changes would be absorbed
|
|
but absorb --dry-run
|
|
|
|
# Absorb into new commits instead of amending
|
|
but absorb --new
|
|
```
|
|
|
|
### Push with Preview
|
|
|
|
```bash
|
|
# See what would be pushed without pushing
|
|
but push --dry-run
|
|
|
|
# Push a specific branch
|
|
but push feature-auth
|
|
|
|
# Push all unpushed branches
|
|
but push
|
|
```
|
|
|
|
---
|
|
|
|
## Tips and Patterns
|
|
|
|
### Branch Naming
|
|
|
|
```bash
|
|
# Agent-based naming
|
|
but branch new claude-feat-user-auth
|
|
but branch new droid-fix-api-timeout
|
|
|
|
# Task-based naming
|
|
but branch new feature-authentication
|
|
but branch new bugfix-timeout
|
|
```
|
|
|
|
### Snapshot Cadence
|
|
|
|
```bash
|
|
but oplog snapshot --message "Before major reorganization"
|
|
but oplog snapshot --message "Before multi-agent coordination"
|
|
but oplog snapshot --message "Before complex stack changes"
|
|
```
|
|
|
|
### File Assignment Discipline
|
|
|
|
```bash
|
|
# Good: Assign immediately
|
|
echo "code" > file1.ts
|
|
but rub <id> my-branch # Right away
|
|
```
|
|
|
|
### JSON Output
|
|
|
|
```bash
|
|
# Get branch commits
|
|
but show feature-branch --json | jq '.commits[] | .id'
|
|
|
|
# Workspace overview
|
|
but status --json | jq '.stacks'
|
|
```
|