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)

Housekeeping

git hide <hash>           # Hide commit from smartlog
git unhide <hash>         # Restore hidden commit

Recovery

git undo                  # Undo last operation (with confirmation)
git undo -i               # Interactive undo — browse history

Common Workflows

Building a Stack

git checkout --detach
git record -m "feat: first feature"
git record -m "feat: second feature"
git record -m "feat: third feature"
git sl   # View your stack

Fixing a Middle Commit

git prev 2                # Go to the commit to fix
# make changes...
git add . && git amend    # Amend + restack descendants
git next 2                # Return to top

Creating PRs for a Stack

# For each commit, create branch and submit
git prev 2
git switch -c pr/first-feature
git submit -c @

git next
git switch -c pr/second-feature
git submit -c @

git next
git switch -c pr/third-feature
git submit -c @

Setting Stacked PR Base Branches

For true stacked PRs on GitHub:

PR	Base Branch
pr/first-feature	main
pr/second-feature	pr/first-feature
pr/third-feature	pr/second-feature

After PR Merge

git pull origin main
git sl   # Find merge commit hash
git move -s <next-commit> -d <merge-commit-hash>
# Recreate branches for remaining commits
git switch -c pr/remaining-feature
git submit -c @

Syncing with Updated Main

git sync --pull           # Fetch + rebase stack
git submit                # Update all PRs

Recovering from Mistakes

git undo -i               # Browse history, find good state, restore

Interactive Rebase Operations

git rebase -i main

In the editor:

• pick — keep commit as-is
• drop — remove commit
• fixup — squash into previous (discard message)
• squash — squash into previous (combine messages)
• Reorder lines to change commit order

Best Practices

1. Always detach before stacking - Use git checkout --detach or git record -d
2. Use git amend instead of git commit --amend - It auto-restacks descendants
3. Use git record instead of git add + git commit - Simpler workflow
4. Run git restack after manual amends - Fixes abandoned commits
5. Use git sync --pull regularly - Keep stack updated with main
6. Create branches only when ready to PR - Use git switch -c or git record -c
7. Force-push updates with git submit - Updates all stacked PRs at once

Troubleshooting

"Abandoned commits (✕) showing in smartlog"

git restack               # Rebase descendants onto amended commit

"git sl only shows main / no stack visible"

You committed on main. Fix:

git checkout --detach
git branch -f main <initial-commit-hash>

"git submit @ does nothing / skipped"

You need a branch AND --create:

git switch -c pr/my-feature
git submit -c @

"Messy graph after PR merge"

Move remaining commits onto merge commit:

git pull origin main
git sl   # Find merge commit hash
git move -s <next-commit> -d <merge-commit-hash>

"Conflict during restack or sync"

# Resolve conflicts in files
git add <resolved-files>
git rebase --continue