branchless-workflow

Git-branchless stacked diffs workflow patterns and command reference

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/git-workflow/skills/branchless-workflow/SKILL.md

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

Always detach before stacking - Use git checkout --detach or git record -d
Use git amend instead of git commit --amend - It auto-restacks descendants
Use git record instead of git add + git commit - Simpler workflow
Run git restack after manual amends - Fixes abandoned commits
Use git sync --pull regularly - Keep stack updated with main
Create branches only when ready to PR - Use git switch -c or git record -c
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

Repository: jpoutrin/product-forge
Path: plugins/git-workflow/skills/branchless-workflow/SKILL.md
Commit: 0ebe7ae

Last updated: 5 days ago
First committed: 6 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.