📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,238 @@
|
||||
# AI Integration Reference
|
||||
|
||||
GitButler provides hooks, MCP server, and GUI features for AI agent integration.
|
||||
|
||||
---
|
||||
|
||||
## Lifecycle Hooks
|
||||
|
||||
GitButler CLI commands that can be called from AI agent lifecycle hooks.
|
||||
|
||||
### Claude Code Hooks
|
||||
|
||||
Add to `.claude/hooks.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "but claude pre-tool"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "but claude post-tool"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "but claude stop"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Hook commands:**
|
||||
|
||||
| Command | Trigger | Purpose |
|
||||
|---------|---------|---------|
|
||||
| `but claude pre-tool` | Before Edit/Write | Prepare workspace, snapshot |
|
||||
| `but claude post-tool` | After Edit/Write | Auto-assign changes |
|
||||
| `but claude stop` | Session ends | Finalize commits, cleanup |
|
||||
|
||||
### Cursor Hooks
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"after-edit": "but cursor after-edit",
|
||||
"stop": "but cursor stop"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Hook commands:**
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `but cursor after-edit` | Auto-assign/commit after Cursor edits |
|
||||
| `but cursor stop` | Finalize when task completes |
|
||||
|
||||
---
|
||||
|
||||
## MCP Server
|
||||
|
||||
Start GitButler's MCP server for programmatic agent access:
|
||||
|
||||
```bash
|
||||
but mcp
|
||||
```
|
||||
|
||||
### Available Tool
|
||||
|
||||
**`gitbutler_update_branches`**
|
||||
|
||||
Updates commits based on prompt and changes. Designed for async processing:
|
||||
|
||||
1. Agent calls after making code changes
|
||||
2. GitButler records changes + prompt immediately (returns fast)
|
||||
3. Processing happens asynchronously to create commits
|
||||
|
||||
**Input schema:**
|
||||
|
||||
```typescript
|
||||
{
|
||||
prompt: string // Description of changes made
|
||||
}
|
||||
```
|
||||
|
||||
**Current limitations:**
|
||||
|
||||
- No branch creation via MCP
|
||||
- No stack management
|
||||
- No push/submit operations
|
||||
- No branch navigation
|
||||
- No restack commands
|
||||
|
||||
**Future roadmap (from GitButler docs):**
|
||||
|
||||
- Auto-absorbing changes into existing commits
|
||||
- Creating new branches based on prompt theme
|
||||
- Creating stacked branches
|
||||
- More sophisticated commit organization
|
||||
|
||||
---
|
||||
|
||||
## Agents Tab (GUI)
|
||||
|
||||
GitButler GUI provides an Agents Tab for Claude Code integration:
|
||||
|
||||
1. **Branch-Agent Binding**: Each virtual branch can be tied to an agent session
|
||||
2. **Parallel Execution**: Multiple agents run simultaneously, isolated by branch
|
||||
3. **Automatic Commit Management**: Agent work auto-committed to their branch
|
||||
4. **Session Persistence**: Agent context preserved across restarts
|
||||
|
||||
### Setup
|
||||
|
||||
1. Open GitButler GUI for repo: `but gui`
|
||||
2. Navigate to Agents Tab
|
||||
3. Create agent sessions tied to virtual branches
|
||||
4. Configure which branches each agent can modify
|
||||
|
||||
---
|
||||
|
||||
## Agent Workflow Patterns
|
||||
|
||||
### Pattern 1: Hook-Based Auto-Commit
|
||||
|
||||
Let GitButler handle commits automatically:
|
||||
|
||||
```bash
|
||||
# Agent instruction
|
||||
"Never use the git commit command after a task is finished"
|
||||
```
|
||||
|
||||
PostToolUse hook creates commits automatically.
|
||||
|
||||
### Pattern 2: Explicit Agent Commits
|
||||
|
||||
Agent controls commit timing:
|
||||
|
||||
```bash
|
||||
# Agent creates branch
|
||||
but branch new agent-feature
|
||||
|
||||
# Agent makes changes...
|
||||
|
||||
# Agent assigns and commits explicitly
|
||||
but rub <file-id> agent-feature
|
||||
but commit agent-feature -m "feat: implementation"
|
||||
```
|
||||
|
||||
### Pattern 3: Multi-Agent with Marks
|
||||
|
||||
Set up auto-assignment for agent branches:
|
||||
|
||||
```bash
|
||||
# Agent A's branch receives new changes
|
||||
but mark agent-a-auth
|
||||
|
||||
# Agent B's branch receives new changes
|
||||
but mark agent-b-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Agent Instructions
|
||||
|
||||
When configuring agents to work with GitButler:
|
||||
|
||||
1. **Never use `git commit`** - Breaks GitButler state
|
||||
2. **Never use `git add`** - GitButler manages index
|
||||
3. **Never use `git checkout`** - All branches always applied
|
||||
4. **Always return to workspace** after any git operations: `git checkout gitbutler/workspace`
|
||||
5. **Use `but status` to find file IDs** before using `but rub`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent commit "orphaned"
|
||||
|
||||
**Cause:** Agent used `git commit` instead of `but commit`.
|
||||
|
||||
**Solution:**
|
||||
|
||||
```bash
|
||||
git reflog # Find orphaned commit
|
||||
but branch new recovered-work
|
||||
# Manually apply changes or cherry-pick
|
||||
```
|
||||
|
||||
### MCP server not responding
|
||||
|
||||
**Cause:** Feature may be behind experimental flag.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check GitButler version (0.16+)
|
||||
2. Enable experimental features in GUI settings
|
||||
3. Restart `but mcp`
|
||||
|
||||
### Hooks not triggering
|
||||
|
||||
**Verify:**
|
||||
|
||||
1. Hook file location correct (`.claude/hooks.json`)
|
||||
2. JSON syntax valid
|
||||
3. `but` command in PATH
|
||||
4. GitButler initialized in repo
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [GitButler MCP Server Docs](https://docs.gitbutler.com/features/ai-integration/mcp-server)
|
||||
- [Claude Code Hooks Docs](https://docs.gitbutler.com/features/ai-integration/claude-code-hooks)
|
||||
- [Cursor Hooks Docs](https://docs.gitbutler.com/features/ai-integration/cursor-hooks)
|
||||
- [Agents Tab Blog Post](https://blog.gitbutler.com/agents-tab)
|
||||
@@ -0,0 +1,402 @@
|
||||
# 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'
|
||||
```
|
||||
@@ -0,0 +1,534 @@
|
||||
# GitButler Reference
|
||||
|
||||
Complete CLI reference, JSON schemas, troubleshooting, and recovery patterns.
|
||||
|
||||
---
|
||||
|
||||
## Command Reference
|
||||
|
||||
### Global Options
|
||||
|
||||
```bash
|
||||
but [OPTIONS] <COMMAND>
|
||||
|
||||
Global Options (must come BEFORE subcommand):
|
||||
-C, --current-dir <PATH> Run from specified directory
|
||||
-j, --json JSON output format
|
||||
-h, --help Show help
|
||||
```
|
||||
|
||||
**JSON output**: Use `--json` or `-j` per command, or as a global flag:
|
||||
|
||||
```bash
|
||||
but status --json # Per-command flag
|
||||
but --json status # Global flag (also works)
|
||||
```
|
||||
|
||||
### Inspection Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but status` | View uncommitted changes and file assignments |
|
||||
| `but status -f` | Show modified files in each commit |
|
||||
| `but status -v, --verbose` | Show verbose output with commit author and timestamp |
|
||||
| `but show <id>` | Show detailed info about a commit or branch |
|
||||
| `but diff` | Show diff of all uncommitted changes |
|
||||
| `but diff <id>` | Show diff for a specific entity (file, branch, commit) |
|
||||
| `but oplog` | View operations history (snapshots) |
|
||||
| `but gui` | Open GitButler GUI for current repo |
|
||||
|
||||
**Status Output Example:**
|
||||
|
||||
```
|
||||
╭┄00 [Unassigned Changes]
|
||||
│ m6 A test-file.md
|
||||
│ p9 M existing-file.ts
|
||||
├╯
|
||||
|
||||
╭┄g4 [feature-branch]
|
||||
│ 🔒 i3 M locked-file.ts
|
||||
● abc1234 feat: initial commit
|
||||
├╯
|
||||
|
||||
● 0c60c71 (common base) [origin/main]
|
||||
```
|
||||
|
||||
**File Status Codes:**
|
||||
- `A` — Added
|
||||
- `M` — Modified
|
||||
- `D` — Deleted
|
||||
- `🔒` — Locked (belongs to this branch's commits)
|
||||
|
||||
**IDs:**
|
||||
- `00`, `g4` — Branch IDs
|
||||
- `m6`, `p9`, `i3` — File/hunk IDs (use with `but rub`)
|
||||
|
||||
### Branch Management
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but branch new <name>` | Create virtual branch (based on trunk) |
|
||||
| `but branch new <name> --anchor <parent>` | Create stacked branch |
|
||||
| `but branch new <name> -a <parent>` | Short form for stacked branch |
|
||||
| `but branch delete <name>` | Soft delete (requires confirmation) |
|
||||
| `but branch delete <name> --force` | Force delete |
|
||||
| `but branch list` | List all branches |
|
||||
| `but branch list --local` | Only local branches |
|
||||
| `but unapply <name>` | Remove branch from workspace (keeps in Git) |
|
||||
| `but apply <name>` | Apply an unapplied branch to workspace |
|
||||
| `but pick <source> [branch]` | Cherry-pick commit from unapplied branch |
|
||||
|
||||
### Committing
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but commit -m "message"` | Commit to inferred branch |
|
||||
| `but commit <branch> -m "message"` | Commit to specific branch |
|
||||
| `but commit <branch> -o -m "msg"` | Only commit assigned files (`-o` flag) |
|
||||
| `but commit -p <id>,<id>` | Commit specific files/hunks by CLI ID |
|
||||
| `but commit --ai` | Generate commit message with AI |
|
||||
| `but commit -c` | Create new branch for this commit |
|
||||
| `but commit` | Opens `$EDITOR` for message |
|
||||
| `but commit empty --before <target>` | Insert blank commit before target |
|
||||
| `but commit empty --after <target>` | Insert blank commit after target |
|
||||
|
||||
**Note:** Unlike git, GitButler commits all changes by default. Use `-o/--only` to commit only assigned files, or `-p/--changes` to select specific file/hunk IDs.
|
||||
|
||||
### File and Commit Manipulation
|
||||
|
||||
#### `but rub` (Swiss Army Knife)
|
||||
|
||||
```bash
|
||||
but rub <source> <target>
|
||||
```
|
||||
|
||||
| Source | Target | Operation | Description |
|
||||
|--------|--------|-----------|-------------|
|
||||
| File ID | Branch ID | **Assign** | Move file to branch |
|
||||
| File ID | Commit SHA | **Amend** | Add file changes to commit |
|
||||
| Commit SHA | Branch ID | **Move** | Relocate commit to branch |
|
||||
| Commit SHA | Commit SHA | **Squash** | Combine newer into older |
|
||||
|
||||
#### Other Editing Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but commit empty --before/--after <target>` | Insert blank commit before or after target |
|
||||
| `but reword` | Edit commit message or rename branch |
|
||||
| `but absorb` | Auto-amend uncommitted changes to appropriate commits based on context |
|
||||
| `but absorb --dry-run` | Preview what absorb would do without changing anything |
|
||||
| `but absorb --new` | Create new commits instead of amending existing ones |
|
||||
| `but squash <commits>` | Squash commits together (by IDs, range, or branch name) |
|
||||
| `but move <commit> <target>` | Move commit to a different location in the stack |
|
||||
| `but amend <file> <commit>` | Amend a file change into a specific commit |
|
||||
| `but uncommit <source>` | Uncommit changes back to unstaged area |
|
||||
| `but discard <id>` | Discard uncommitted changes from worktree |
|
||||
| `but mark <branch>` | Auto-assign new changes to branch |
|
||||
| `but unmark` | Remove all mark rules from workspace |
|
||||
|
||||
**`but absorb`**: Analyzes uncommitted changes and automatically amends them to the appropriate existing commits based on file context and change location. Similar to `git absorb` but integrated with virtual branches.
|
||||
|
||||
### Forge Integration (GitHub)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but config forge auth` | Authenticate with GitHub via OAuth flow |
|
||||
| `but config forge list-users` | List authenticated accounts |
|
||||
| `but config forge forget <username>` | Remove authenticated account |
|
||||
| `but push [branch]` | Push branch to remote |
|
||||
| `but push -d, --dry-run` | Preview what would be pushed |
|
||||
| `but push -f, --with-force` | Force push |
|
||||
| `but push -r, --run-hooks` | Execute pre-push hooks |
|
||||
| `but pr new [branch]` | Create PR for branch on forge |
|
||||
|
||||
**Push + PR workflow:**
|
||||
1. Push branch to remote: `but push feature-auth`
|
||||
2. Create PR: `but pr new feature-auth`
|
||||
3. Or push all unpushed branches: `but push` (non-interactive)
|
||||
4. Requires prior `but config forge auth` for first-time setup
|
||||
|
||||
### Base Branch Operations
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but pull --check` | Fetch remotes and check mergeability |
|
||||
| `but pull` | Update workspace with latest from base |
|
||||
|
||||
### Operations History (Undo/Restore)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but oplog` | View operation history |
|
||||
| `but undo` | Undo last operation |
|
||||
| `but oplog restore <snapshot-id>` | Restore to specific snapshot |
|
||||
| `but oplog snapshot --message "msg"` | Create manual snapshot |
|
||||
|
||||
### Conflict Resolution
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but resolve <commit-id>` | Enter resolution mode for a conflicted commit |
|
||||
| `but resolve status` | Show remaining conflicted files |
|
||||
| `but resolve finish` | Finalize resolution and return to workspace |
|
||||
| `but resolve cancel` | Cancel resolution and return to workspace |
|
||||
|
||||
**Workflow:**
|
||||
1. `but status` shows conflicted commits
|
||||
2. `but resolve <commit-id>` to enter resolution mode
|
||||
3. Fix conflict markers in your editor
|
||||
4. `but resolve status` to check remaining conflicts
|
||||
5. `but resolve finish` to finalize
|
||||
|
||||
### Workspace Lifecycle
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but setup` | Initialize GitButler project from existing Git repo |
|
||||
| `but setup --init` | Initialize new Git repo and set up GitButler |
|
||||
| `but teardown` | Exit GitButler mode, return to normal Git |
|
||||
|
||||
**`but teardown`**: Creates an oplog snapshot, checks out the first active branch as a regular Git branch, and provides instructions for returning to GitButler mode.
|
||||
|
||||
### Configuration
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `but config` | Show configuration overview |
|
||||
| `but config user` | View user configuration |
|
||||
| `but config user set name "Name"` | Set user name |
|
||||
| `but config user set email "email"` | Set user email |
|
||||
| `but config forge` | View forge configuration |
|
||||
| `but config forge auth` | Authenticate with forge (GitHub OAuth) |
|
||||
| `but config forge list-users` | List authenticated accounts |
|
||||
| `but config forge forget <user>` | Remove authenticated account |
|
||||
|
||||
### AI Integration Commands
|
||||
|
||||
**Claude Code Hooks:**
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `but claude pre-tool` | Run before code generation/editing |
|
||||
| `but claude post-tool` | Run after editing completes |
|
||||
| `but claude stop` | Run when agent session ends |
|
||||
|
||||
**Cursor Hooks:**
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `but cursor after-edit` | Triggered when Cursor edits files |
|
||||
| `but cursor stop` | Triggered when task completes |
|
||||
|
||||
**MCP Server:**
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `but mcp` | Start MCP server for agent integration |
|
||||
|
||||
---
|
||||
|
||||
## JSON Output Schemas
|
||||
|
||||
### `but status --json`
|
||||
|
||||
Key fields:
|
||||
- `path` — Filename as ASCII array (requires decoding)
|
||||
- `assignments` — Hunk-level file assignments
|
||||
- `stackId` — Which stack this belongs to (null if unassigned)
|
||||
|
||||
**Limitations:**
|
||||
- File IDs (`m6`, `g4`) not exposed in JSON
|
||||
- Paths are ASCII arrays, not strings
|
||||
- Parse text output for IDs
|
||||
|
||||
### `but show <branch> --json`
|
||||
|
||||
Shows detailed branch info with commits. Key fields:
|
||||
- `commits` — Array of commits on the branch
|
||||
- `commits[].id` — Commit SHA
|
||||
|
||||
### `but diff --json`
|
||||
|
||||
Shows diffs in JSON format for programmatic analysis.
|
||||
|
||||
**Useful jq patterns:**
|
||||
|
||||
```bash
|
||||
# Get branch commits
|
||||
but show feature-branch --json | jq '.commits[] | .id'
|
||||
|
||||
# Workspace overview
|
||||
but status --json | jq '.stacks'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GitButler vs Graphite
|
||||
|
||||
| Aspect | Graphite | GitButler |
|
||||
|--------|----------|-----------|
|
||||
| **Model** | Linear stacks of physical branches | Virtual branches with optional stacking |
|
||||
| **Workflow** | Plan → Branch → Code → Commit → Stack | Code → Organize → Assign → Commit |
|
||||
| **Branch Switching** | Required (`gt up`/`gt down`) | Never needed (all applied) |
|
||||
| **Branch Creation** | `gt create -am "msg"` | `but branch new name [--anchor parent]` |
|
||||
| **Committing** | `gt modify -cam "msg"` | `but commit -m "msg"` |
|
||||
| **Stack Navigation** | ✓ `gt up`/`gt down` | ✗ No CLI equivalent (all applied) |
|
||||
| **PR Submission** | ✓ `gt submit --stack` | ✓ `but push` + `but pr new` |
|
||||
| **JSON Output** | Limited | ✓ Comprehensive via `--json` per command |
|
||||
| **Multi-Feature Work** | Switch branches | All in one workspace |
|
||||
| **CLI Completeness** | ✓ Full automation | ✓ Full automation (as of 0.19.0) |
|
||||
| **Conflict Resolution** | Standard git rebase | ✓ Per-commit via `but resolve` |
|
||||
|
||||
**Choose Graphite when:**
|
||||
- Stack navigation commands needed (`gt up`/`gt down`)
|
||||
- Terminal-first linear workflow
|
||||
- Established stacked PR practices
|
||||
|
||||
**Choose GitButler when:**
|
||||
- Multiple unrelated features simultaneously
|
||||
- Multi-agent concurrent development
|
||||
- Exploratory coding (organize after)
|
||||
- Post-hoc commit reorganization
|
||||
- Per-commit conflict resolution needed
|
||||
- Visual organization preferred (GUI + CLI)
|
||||
|
||||
**Don't use both in same repo** — incompatible models.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### Quick Reference
|
||||
|
||||
| Symptom | Cause | Solution |
|
||||
|---------|-------|----------|
|
||||
| Broken pipe panic | Output piped directly | Capture to variable first |
|
||||
| Filename with dash fails | Interpreted as range | Use file ID from `but status` |
|
||||
| Branch not visible | Not applied | `but apply <branch>` or `but pick <commit>` |
|
||||
| Files not committing | Not assigned | `but rub <file-id> <branch>` |
|
||||
| Mixed git/but broke state | Used git commands | `but pull` or `but setup` |
|
||||
| Workspace stuck loading | Backend timeout | Check oplog, restore snapshot |
|
||||
| "Workspace commit not found" | HEAD changed externally | `git checkout gitbutler/workspace` |
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Broken Pipe Panic
|
||||
|
||||
**Problem:** `but status` panics when output consumed partially.
|
||||
|
||||
```bash
|
||||
✗ but status | head -5 # Panic!
|
||||
|
||||
✓ status_output=$(but status)
|
||||
echo "$status_output" | head -5
|
||||
```
|
||||
|
||||
#### Filename Parsing Issues
|
||||
|
||||
**Problem:** Dashes in filenames interpreted as range syntax.
|
||||
|
||||
```bash
|
||||
✗ but rub file-with-dashes.md branch # Fails
|
||||
|
||||
✓ but rub m6 branch # Use file ID from but status
|
||||
```
|
||||
|
||||
#### Integration Branch Conflicts
|
||||
|
||||
**Problem:** Mixed `git` and `but` commands corrupted state.
|
||||
|
||||
**Solutions:**
|
||||
1. `but pull` to resync
|
||||
2. If severely broken: `but setup` to reinitialize
|
||||
|
||||
#### Files Not Committing
|
||||
|
||||
**Causes:**
|
||||
1. Files not assigned to branch
|
||||
2. Missing `-o` flag (only commit assigned files)
|
||||
|
||||
```bash
|
||||
# Check assignments
|
||||
but status
|
||||
|
||||
# Assign files
|
||||
but rub <file-id> <branch>
|
||||
|
||||
# Commit with -o flag
|
||||
but commit <branch> -o -m "message"
|
||||
```
|
||||
|
||||
#### Workspace Stuck Loading
|
||||
|
||||
**Symptoms:**
|
||||
- Loading spinner indefinitely
|
||||
- Can see trunk/remote branches but not workspace
|
||||
|
||||
**Recovery:**
|
||||
1. Wait 60 seconds for timeout
|
||||
2. Check logs: `~/Library/Logs/com.gitbutler.app/GitButler.log` (macOS)
|
||||
3. Use Operations History to restore previous snapshot
|
||||
4. Last resort: Remove and re-add project
|
||||
|
||||
#### "GitButler workspace commit not found"
|
||||
|
||||
**Cause:** `gitbutler/workspace` branch modified or deleted outside GitButler.
|
||||
|
||||
**Recovery:**
|
||||
|
||||
```bash
|
||||
# Return to integration branch
|
||||
git checkout gitbutler/integration
|
||||
|
||||
# If that fails, check oplog
|
||||
cat .git/gitbutler/operations-log.toml
|
||||
git log <head_sha>
|
||||
|
||||
# Remove and re-add project to GitButler
|
||||
```
|
||||
|
||||
### Recovery Scenarios
|
||||
|
||||
#### Lost Work (Accidentally Deleted Branch)
|
||||
|
||||
```bash
|
||||
# Check oplog for deletion
|
||||
but oplog
|
||||
|
||||
# Undo deletion (if last operation)
|
||||
but undo
|
||||
|
||||
# Or restore to snapshot before deletion
|
||||
but oplog restore <snapshot-id>
|
||||
```
|
||||
|
||||
#### Corrupted Workspace State
|
||||
|
||||
```bash
|
||||
# Step 1: Snapshot current state
|
||||
but oplog snapshot --message "Before recovery"
|
||||
|
||||
# Step 2: Update base
|
||||
but pull
|
||||
|
||||
# Step 3: Last resort - reinitialize
|
||||
but setup
|
||||
```
|
||||
|
||||
#### Recovering from Mixed Git/But Commands
|
||||
|
||||
**If you committed with `git commit`:**
|
||||
|
||||
```bash
|
||||
# Work is still in working directory
|
||||
# Find orphaned commit
|
||||
git reflog
|
||||
|
||||
# Create branch from it
|
||||
git branch recovered <commit-sha>
|
||||
|
||||
# Return to GitButler
|
||||
git checkout gitbutler/integration
|
||||
```
|
||||
|
||||
**If you checked out another branch:**
|
||||
|
||||
```bash
|
||||
# Return to GitButler
|
||||
git checkout gitbutler/integration
|
||||
# GitButler will resume operation
|
||||
```
|
||||
|
||||
#### Virtual Branches Disappeared
|
||||
|
||||
Virtual branches are Git refs — they're still there:
|
||||
|
||||
```bash
|
||||
# List all virtual branch refs
|
||||
git for-each-ref refs/gitbutler/
|
||||
|
||||
# Create regular branch from virtual branch
|
||||
git branch recovered-feature refs/gitbutler/Feature-A
|
||||
|
||||
# Or push directly to remote
|
||||
git push origin refs/gitbutler/Feature-A:refs/heads/feature-a
|
||||
```
|
||||
|
||||
#### Extract Data from Corrupted Project
|
||||
|
||||
```bash
|
||||
# Backup everything
|
||||
cp -r .git .git-backup
|
||||
|
||||
# Extract all virtual branch refs
|
||||
git for-each-ref refs/gitbutler/ > gitbutler-refs.txt
|
||||
|
||||
# Create regular branch from each
|
||||
while read sha type ref; do
|
||||
name=$(basename "$ref")
|
||||
git branch "recovered-$name" "$sha"
|
||||
done < gitbutler-refs.txt
|
||||
|
||||
# Extract latest oplog snapshot
|
||||
LATEST=$(cat .git/gitbutler/operations-log.toml | grep head_sha | awk '{print $3}' | tr -d '"')
|
||||
git archive $LATEST index/ | tar -x -C recovered-uncommitted/
|
||||
```
|
||||
|
||||
### Operations Log (Oplog) Deep Dive
|
||||
|
||||
**Location:** `.git/gitbutler/operations-log.toml`
|
||||
|
||||
**Snapshot contents:**
|
||||
|
||||
```
|
||||
<snapshot-commit>
|
||||
├── virtual_branches.toml # Branch metadata
|
||||
├── virtual_branches/ # Branch content trees
|
||||
├── index/ # Working directory state
|
||||
├── target_tree/ # Base branch (e.g., main)
|
||||
└── conflicts/ # Merge conflict info
|
||||
```
|
||||
|
||||
**Operation types:**
|
||||
- `CreateCommit` — Made a commit
|
||||
- `CreateBranch` — Created branch
|
||||
- `UpdateWorkspaceBase` — Updated base branch
|
||||
- `RestoreFromSnapshot` — Reverted to snapshot
|
||||
- `FileChanges` — Uncommitted changes detected
|
||||
- `DeleteBranch` — Deleted branch
|
||||
- `SquashCommit` — Squashed commits
|
||||
|
||||
**Manual inspection:**
|
||||
|
||||
```bash
|
||||
# Find oplog head
|
||||
OPLOG_HEAD=$(cat .git/gitbutler/operations-log.toml | grep head_sha | awk '{print $3}' | tr -d '"')
|
||||
|
||||
# View snapshot history
|
||||
git log $OPLOG_HEAD --oneline
|
||||
|
||||
# Show virtual branches config from snapshot
|
||||
git show <snapshot-sha>:virtual_branches.toml
|
||||
|
||||
# Extract file from snapshot
|
||||
git show <snapshot-sha>:index/path/to/file.txt
|
||||
```
|
||||
|
||||
### Prevention Best Practices
|
||||
|
||||
**Golden Rules:**
|
||||
1. **NEVER remove project to fix errors** — may delete actual source files
|
||||
2. **Commit frequently** — committed work is safer than WIP
|
||||
3. **Push virtual branches to remote** — backup your work
|
||||
4. **Don't mix GitButler and stock Git commands** — choose one workflow
|
||||
|
||||
**Before risky operations:**
|
||||
|
||||
```bash
|
||||
but oplog snapshot --message "Before major reorganization"
|
||||
```
|
||||
|
||||
**Before GitButler updates:**
|
||||
1. Commit everything
|
||||
2. Push all branches to remote
|
||||
3. Verify Operations History accessible
|
||||
Reference in New Issue
Block a user