Mastering Stacked PRs with git-machete: Don’t Let Git Rebase Get the Best of You

The Nightmare Called “Stacked Pull Requests”

Working on large projects with strict CI/CD pipelines, you’ve likely found yourself stuck in the middle of a chain of Pull Requests (Stacked PRs). You’re coding Feature A, but Feature B needs A’s code to run, and Feature C is waiting on B.

Everything goes smoothly until a reviewer requests logic changes in Feature A. That’s when the rebase nightmare begins. You fix A, then laboriously rebase B onto A, then pull C onto B. One slip-up with the <a href="https://itfromzero.com/en/git-en/git-rebase-onto-mastering-professional-git-history-surgery.html">git rebase --onto</a> command, and your entire commit history turns into a tangled mess.

I once spent an entire morning untangling a chain of five dependent branches. Exhausted, I even accidentally git push --force over a colleague’s code. To avoid these heart-stopping moments, I turned to git-machete.

Why Traditional Branch Management Is Error-Prone

Let’s look at the two most common approaches to see the difference in efficiency.

1. Manual Rebase (The Hard Way)

This is the default approach: you use the git rebase command for each branch individually.

• Cons: Takes an average of 10-15 minutes for a 3-branch chain if there are conflicts. It’s very easy to lose track of branch bases as the chain grows.

2. Using git-machete (The Smart Way)

This tool creates a management layer on top of Git, defining the dependency tree via a configuration file at .git/machete.

• Pros: It takes just one command to update the entire chain. You get a bird’s-eye view of the repo without having to keep it all in your head.

Observability – The Ultimate Weapon of git-machete

The best feature of this tool is the git machete status command. Instead of guessing which branches are outdated, you get a clear tree diagram: synced branches (green), drifted branches (red), and merged branches (grey).

It makes you more confident when using --force-with-lease. You always know exactly where you stand in the dependency chain, rather than guessing and praying every time you push.

Installation in 30 Seconds

Written in Python, this tool is extremely easy to install on any operating system.

# For macOS
brew install git-machete

# For Ubuntu/Linux or Windows (via pip)
pip install git-machete

After installation, navigate to your repo and run the following command to let the tool “learn” your branch structure:

git machete discover

Practical Operations to Save You Time

1. Check the “Health” of Your Branch Chain

This command should be a morning habit when you start working:

git machete status

If a branch appears in red, it’s a signal that you need to update code from its parent branch.

2. Bulk Automated Rebase

Suppose the master branch just had a major update. You want the entire feature-1 -> feature-2 -> feature-3 chain updated accordingly? Just type:

git machete update

The tool will iterate through each branch and perform the rebase for you. If a conflict occurs, it will stop for you to resolve it before continuing the journey.

3. Post-Merge Cleanup (Slide-out)

When feature-1 has been merged into master, you need to connect feature-2 directly to master. Don’t do it manually; use:

git machete slide-out feature-1

Real-World Scenario: Handling Sudden Logic Changes

Imagine your diagram: master -> fix-auth -> add-logging.

Your Team Lead asks you to rename a critical function in fix-auth. As soon as you make the change, the add-logging branch becomes “out of sync” immediately. Instead of struggling to calculate which commit to rebase from, simply type git machete status to see the red zone, then git machete update. Everything is back on track without breaking a sweat.

Tips for Effective Use

• Trust but verify: Always check status before update to ensure the branch tree looks the way you want.
• Don’t forget the config file: If you create new branches manually, run git machete discover or edit the .git/machete file to update the diagram.
• Combine with Aliases: I usually set an alias gm = git machete to type commands faster.

If you’re tired of untangling conflicts every time you work with Stacked PRs, give git-machete a try. It’s not just a tool; it’s a way to protect your focus and “mental health” when working with Git.