branchless-workflow

Git-Branchless Workflow

Git-branchless enables stacked diffs development - working with multiple commits that build on each other, editing any commit in the stack, and managing PRs efficiently.

Core Concepts

Detached HEAD Workflow

In git-branchless, you work in detached HEAD mode. Main stays put while you stack commits above it.

# Always detach before building a stack
git checkout --detach

# Or use git record -d to auto-detach
git record -d -m "feat: first commit"

Smartlog Icons

Icon	Meaning
◆	Public commit (on main branch)
◯	Draft commit (your work in progress)
●	Current HEAD position
✕	Abandoned/hidden commit
ᐅ	Current branch indicator

Essential Commands

Visualization

git sl                    # View commit stack (smartlog)

Navigation

git prev                  # Move to parent commit
git next                  # Move to child commit
git prev N                # Jump N commits up
git next N                # Jump N commits down
git sw -i                 # Interactive commit selector (fuzzy finder)
git sw -i <search>        # Pre-filter by search term

Committing

git record -m "msg"              # Commit all changes (no git add needed)
git record -c pr/name -m "msg"   # Commit + create branch in one step
git record -d -m "msg"           # Detach from branch, then commit
git record -I -m "msg"           # Insert commit in middle, auto-rebase children

Editing Commits

git amend                 # Amend current commit + auto-restack descendants
git reword                # Change commit message + auto-restack
git restack               # Rebase descendants onto amended commit

Moving Commits

git move -s <src> -d <dst>  # Move commit(s) to new parent

Syncing

git sync                  # Rebase stack onto local main
git sync --pull           # Fetch remote + rebase stack

Submitting PRs

git switch -c pr/name     # Create branch at current commit
git submit -c @           # Push current branch to remote (first time)
git submit                # Force-push existing branches (update PRs)