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 &lt;- PR1 &lt;- PR2 &lt;- PR3 &lt;- 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: Stacked branches with vanilla Git, Stacked branches with vanilla Git - Reddit Thread):

Rebasing every branch on top of the latest
Force pushing without messing things up
Retargeting PRs

That's where stacksmith comes in.

Stacksmith (Go Edition) ⚡

A Go-powered version of stacksmith with an interactive CLI. It includes:

🔄 Guided flows for stacking, syncing, and fixing branches
🎨 Stylish user interface built with Bubble Tea and Lip Gloss from charm.sh
🖥️ Full Terminal UI, interactive graph, and DAG visualization (coming soon!)

Install Stacksmith (Go Edition) 🚀

Linux & macOS

brew tap mubbie/homebrew-tap
brew install stacksmith

Or install manually

curl -LO https://github.com/mubbie/stacksmith/releases/latest/download/stacksmith_$(uname -s | tr '[:upper:]' '[:lower:]')_amd64.tar.gz
tar -xzf stacksmith_*.tar.gz
sudo mv stacksmith /usr/local/bin/

Windows

📦 Installer available on GitHub Releases

Once approved, you'll also be able to install via:

winget install Mubbie.Stacksmith

> ℹ️ Note: Winget package is pending approval. We’ll update this once it lands.

Stacksmith Lite 🪶

stacksmith-lite.sh is a zero-installation, dead-simple Bash script for managing stacked branches using vanilla Git.

It works anywhere Git works:

✅ Local dev
✅ CI environments
✅ Remote VMs
✅ No plugins, no wrappers, no setup

Install Stacksmith Lite 🚀

curl -sL https://raw.githubusercontent.com/mubbie/stacksmith/main/scripts/stacksmith-lite.sh -o stacksmith
chmod +x stacksmith
sudo mv stacksmith /usr/local/bin/

Or just alias it:

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:

🌲 Rich, colorized DAG views
🧑🏾‍🏭 Interactive TUI
🧪 Diff previews & branch introspection
💾 Config and logging support
🔌 GitHub/Azure integration

See the full Stacksmith Go Roadmap ➡️

🤝 Contribution

Contributions are welcome! ✨

Fork the project
Create your feature branch (git checkout -b feat/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push)
Open a pull request

Add commands, fix bugs, clean up UI, or just drop a pun. All artisan hands on deck.

📢 Feedback

Got ideas, bugs, or thoughts? Love a bad artisan pun? Open an issue or reach out!

Your feedback makes this tool better (and funnier). 😎

Crafted with love (and corny jokes), by artisans of the stack (mostly GPT-4o). 🧑🏾‍🏭✨

Stacksmith Mubbie

README