GitButler CLI Quick Reference

A quick reference guide for GitButler's command-line interface.

Setup

# Initialize GitButler in a repository
gb init

# Configure GitButler settings
gb config --global user.name "Your Name"
gb config --global user.email "your@email.com"

Virtual Branch Management

Create and List

# Create a new virtual branch
gb branch create <branch-name>
gb branch create feature/new-ui

# List all virtual branches
gb branch list
gb branch ls

# List with details
gb branch list --verbose

Apply/Unapply

# Apply a virtual branch (make it active)
gb branch apply <branch-name>

# Unapply a virtual branch (remove from workspace)
gb branch unapply <branch-name>

# Apply multiple branches
gb branch apply branch1 branch2

Delete

# Delete a virtual branch
gb branch delete <branch-name>
gb branch rm <branch-name>

# Force delete (discard uncommitted changes)
gb branch delete --force <branch-name>

Working with Changes

Status

# Show status of all virtual branches
gb status

# Show status of specific branch
gb status <branch-name>

# Show detailed status
gb status --verbose

Moving Changes

# Move file to a virtual branch
gb move <file-path> <branch-name>

# Move specific hunk to a branch
gb move --hunk <file-path>:<hunk-id> <branch-name>

# Move all changes from one branch to another
gb move --all <source-branch> <target-branch>

Staging and Unstaging

# Stage files in a virtual branch
gb add <file-path> --branch <branch-name>

# Unstage files
gb reset <file-path> --branch <branch-name>

# Stage all changes in a branch
gb add --all --branch <branch-name>

Commits

# Commit changes in a virtual branch
gb commit <branch-name> -m "commit message"

# Commit with detailed message
gb commit <branch-name> -m "Title" -m "Description"

# Amend last commit
gb commit <branch-name> --amend

# Commit all changes in branch
gb commit <branch-name> --all -m "message"

Push and Pull

# Push virtual branch to remote
gb push <branch-name>

# Push to specific remote
gb push <branch-name> origin

# Push all applied branches
gb push --all

# Pull updates from remote
gb pull

# Pull specific branch
gb pull <branch-name>

Integration with Git

# Convert virtual branch to Git branch
gb export <branch-name>

# Import Git branch as virtual branch
gb import <git-branch-name>

# Sync with Git remote
gb sync

# Fetch remote changes
gb fetch

Workspace Management

# Show workspace overview
gb workspace

# Clean workspace (remove unapplied branches)
gb workspace clean

# Reset workspace to clean state
gb workspace reset

# Show workspace statistics
gb workspace stats

Diff and Log

# Show diff for a virtual branch
gb diff <branch-name>

# Show diff for specific file
gb diff <branch-name> <file-path>

# Show commit history
gb log <branch-name>

# Show compact log
gb log <branch-name> --oneline

# Show log with graph
gb log --graph --all

Collaboration

# Create pull request from virtual branch
gb pr create <branch-name>

# List pull requests
gb pr list

# Checkout pull request
gb pr checkout <pr-number>

Configuration

# View all configuration
gb config --list

# Set configuration value
gb config <key> <value>

# Set global configuration
gb config --global <key> <value>

# Common configurations
gb config core.editor vim
gb config core.autoPush true
gb config ui.theme dark

Utilities

# Check GitButler version
gb --version
gb version

# Get help
gb help
gb <command> --help

# Update GitButler CLI
gb update

# Verify repository status
gb doctor

Common Workflows

Start New Feature

gb branch create feature/user-auth
gb branch apply feature/user-auth
# Make changes...
gb add --all --branch feature/user-auth
gb commit feature/user-auth -m "Add user authentication"
gb push feature/user-auth

Work on Multiple Features

# Create and apply multiple branches
gb branch create feature/ui
gb branch create feature/api
gb branch apply feature/ui feature/api

# Work on code, then assign changes
gb move src/ui/component.js feature/ui
gb move src/api/endpoint.js feature/api

# Commit separately
gb commit feature/ui -m "Update UI"
gb commit feature/api -m "Add API endpoint"

Quick Fix While Working

# Create hotfix branch
gb branch create hotfix/critical-bug
gb branch apply hotfix/critical-bug

# Move relevant changes
gb move src/buggy-file.js hotfix/critical-bug

# Commit and push immediately
gb commit hotfix/critical-bug -m "Fix critical bug"
gb push hotfix/critical-bug

Review Before Pushing

# Check what's in each branch
gb status
gb diff feature/my-feature

# Review commits
gb log feature/my-feature

# Push when ready
gb push feature/my-feature

Tips

Use gb as shorthand for gitbutler
Tab completion works for branch names
Most commands accept multiple branch names
Use --dry-run flag to preview actions
Use --verbose or -v for detailed output
Chain commands with && for workflows

Environment Variables

# Set GitButler data directory
export GB_DATA_DIR=~/.gitbutler

# Enable debug mode
export GB_DEBUG=1

# Set default editor
export GB_EDITOR=nvim

Aliases

Create shell aliases for common operations:

# Add to ~/.bashrc or ~/.zshrc
alias gbs='gb status'
alias gbl='gb branch list'
alias gbc='gb commit'
alias gbp='gb push'
alias gba='gb branch apply'
alias gbu='gb branch unapply'

Back to GitButler Overview