Stacksmith is an ultralight artisan Git stacking tool designed to manage stacked pull branches and pull requests using vanilla Git. It simplifies the process of breaking work into small, focused branches while maintaining efficient collaboration.
Key Features:
Stacked Branch Management: Easily create, sync, and fix stacked branches with guided flows.
ASCII Commit Graph Visualization: Visualize branch relationships and commit history for clarity.
Go-Powered CLI (Upcoming): Offers an interactive TUI with rich features like diff previews and config support.
Install via winget: Coming soon for easy installation.
Audience & Benefit:
Ideal for developers managing complex features or long-running tasks. Stacksmith helps break work into manageable PRs, enabling continuous progress without delays. It streamlines Git operations, reduces manual errors, and enhances workflow efficiency, making it easier to maintain clean stacks for better code reviews and faster delivery.
README
Stacksmith
> Ultralight Artisan Git Stacking Tool
> (Forgive the corny jokes — staying on brand 🧑🏾🏭)
Stacksmith is your terminal blacksmithing forge for managing stacked pull branches and pull requests using vanilla Git 🌳
This repo contains two versions:
Version
Description
Status
stacksmith-lite.sh
🪶 Lightweight Bash script for fast Git stacking
✅ Stable
stacksmith
⚡ Upcoming Go-powered CLI with rich UI (coming soon)
🚧 In Progress
Why Stacksmith? 🤔
Imagine this: you're building a big feature. It's going to touch a lot of files and introduce a lot of changes.
With traditional Git workflows, your options are usually:
🫠 Put it all in one huge branch → easy for you, painful for your reviewers.
⏳ Break it into many small PRs → good for reviewers, but you end up stuck waiting for each PR to merge before you can build on the next one.
Both kinda suck.
Option 1 → One giant PR 😱
Option 2 → Many PRs but blocked 😩
Stacksmith → Many PRs. Keep shipping 🚀
What Are Stacked PRs? 🚂
Stacked PRs let you break work into small, focused branches — each building on top of the last.
main <- PR1 <- PR2 <- PR3 <- PR4 ...
Each PR targets the previous one, reviewers see small diffs, and you keep moving fast.
BUT managing these stacks manually with plain Git is tedious (See: , ):
alias stacksmith='bash /path/to/stacksmith-lite.sh'
If you run into trouble adding stacksmith to your path, here's an excellent and helpful article recommended by my friend Osaro 🙂
Usage ⚙️
🧩 Launch Interactive UI (In Go Edition)
stacksmith
🪵 Create a new stacked branch
stacksmith stack
🧽 Rebase and sync your stack
stacksmith sync ...
🔧 Rebase a branch after parent PR merges
stacksmith fix-pr
⬆️ Push current branch safely
stacksmith push
🌳 Visualize your branch stack
stacksmith graph
> Prints an ASCII-style Git commit graph with branch tips and relationships.
Managing PRs with Stacksmith 📂
> Stacksmith helps you manage your local branches beautifully. But your PRs will still need to be created, managed, and merged manually on your Git hosting platform (Azure DevOps, GitHub, GitLab, Bitbucket, etc).
PR Lifecycle with Stacksmith
Create your stacked branches locally with stacksmith stack
Push them with stacksmith push
Open PRs in your Git platform (targeting their parent branches, ex: ex: PR2 targets PR1, PR3 targets PR2, etc.)
Merge PRs bottom-up (base first, then next, then next)
After each PR merge:
Use stacksmith fix-pr to rebase the next branch onto the new target (usually main)
Retarget the PR in your Git platform to point to main
Push again with stacksmith push
Pro Tip
Use stacksmith sync to quickly rebase and update a full stack when many PRs have merged.
Stacksmith = Local branch management magic
Your Git platform = PR creation, review, merging
Together = Dev happiness 🌟
What Stacksmith Doesn't Do 🙅
❌ Create PRs for you (use your Git platform)
❌ Auto-retarget PRs (you do that manually)
❌ Auto-detect your stack (you pass branch names explicitly)
Stacksmith stays simple & bashy — that's the point.
Gotchas & Pitfalls 🔦
> Some common sharp edges when working with stacked PRs (and how to avoid them):
Situation
What Happens
How To Handle
PR merges out of order
Git history gets messy; later PR shows unexpected changes
Rebase your branch onto main using stacksmith fix-pr and retarget the PR
Forgetting to retarget PR
PR shows extra unrelated commits
Always retarget PR to main (or the correct parent) after parent merges
Not force-pushing after rebase
Remote branch gets out of sync with local
Always use stacksmith push (safe force-push) after rebasing
Accidentally rebasing wrong parent
Changes vanish or conflict
Double-check the branch order when using stacksmith sync
Final Rule of Thumb:
Merge PRs from the bottom up
Rebase child branches immediately after parent merges
Retarget PRs accordingly
Push your changes
Clean stack = Happy reviewers + Happy you 🌱
Coming Soon in Stacksmith (Go Edition) ⚡
We’re rebuilding Stacksmith in Go for a more powerful and visual CLI experience:
