|new 0.10.14||Mar 16, 2023|
|0.10.12||Feb 2, 2023|
|0.8.5||Sep 6, 2022|
|0.8.3||Jul 2, 2022|
|0.5.3||Nov 14, 2021|
#164 in Development tools
260 downloads per month
Stacked branch management for Git
Dual-licensed under MIT or Apache 2.0
git-stack is another approach to bringing the
Stacked Diff workflow
to PRs/branches that aims to be unintrusive to a project's workflow. Branches are the unit
of work and review in
git-stack. As you create branches on top of each
other (i.e. "stacked" branches),
git-stack will takes care of all of the
micromanagement for you.
Unfamiliar with Stacked-Diffs?
git-stack helps automate a lot of common
workflows when dealing with PRs, especially when you start to create PRs on top
- Upstream parent branch auto-detection
- Maintain branches relative to each other through rebase
- Defers all permanent changes until the end (e.g. HEAD, re-targeting
branches), always leaving you in a good state
- Separates out pull/push remotes for working from a fork
--push, detects which branches are "ready" (e.g. root of stack, no WIP)
- Undo support: backs up branch state prior to rewriting history
- Conflict resolution:
git-stackwill give up and you'll have to use
git rebaseyourself to resolve the conflict.
To see how
git-stack compares to other stacked git tools, see the Comparison.
From your feature branch, run:
jira-3423423 $ git stack --pull
git stack --pull:
- Auto-detects your parent remote branch (e.g.
- Performs a
git pull --rebase <remote> <parent>
jira-3423423(and any dev branches on the stack) onto
- Shows the stacked branches
See Getting Start for a complete workflow example.
The closest equivalent is:
jira-3423 $ git checkout main main $ git pull --rebase upstream main main $ git checkout jira-3154 jira-3154 $ git rebase HEAD~~ --onto main jira-3154 $ git checkout jira-3259 jira-3259 $ git rebase HEAD~ --onto jira-3154 jira-3259 $ git checkout jira-3423 jira-3423 $ git rebase HEAD~ --onto jurao-3259 jira-3423 $ git log --graph --all --oneline --decorate main..HEAD
For more, see Command Reference
Parent branch auto-detection works by separating the concept of upstream-controlled branches (called "protected branches") and your development branches.
Download a pre-built binary (installable via gh-install).
Or use rust to install:
$ cargo install git-stack
We also recommend installing
git-branch-stash for easily
git stack operations:
$ cargo install git-branch-stash-cli
Aliases: To avoid name collisions while keeping things brief,
ships as one binary but can help configure aliases by running
git stack alias --register. You can then modify the aliases if you want to make
some flags the default.
Protected branches: These are branches that
git-stack should not modify.
git-stack will also rebase local protected branches against
their remote counter parts. Usually you mark shared or long-lived branches as
git-stack --protected -v to test your config
- To locally protect additional branches, run
git-stack --protect <glob>.
- When adopting
git-stackas a team, you can move the protected branches from
$REPO/.gitconfigand commit it.
Pull remote when working from a fork, where upstream is a different remote than
git config --add stack.pull-remote <REMOTE> to set your remote in
To see the config, run
git-stack --dump-config -.
For more, see Configuration Reference.
If you registered aliases, you'll want to run
git stack alias --unregister to remove them.
See the uninstall method for your installer.
git-stack leaves behind:
Removing this is safe and will have no effect.
$ # Update branches against upstream $ git sync $ # Start a new branch / PR $ git switch -c feature1 $ git add -A; git commit -m "Work" $ git add -A; git commit -m "More Work" $ git run cargo check $ git prev $ git add -A; git amend # Fix problems in "Work" commit $ git run cargo check $ git next $ # See what this looks like $ git stack $ # Clean up in preparation for a push $ git sync $ # Push whats ready $ git stack --push
For more, see Command Reference.
When should my branches be stacked?
This is up to you. Some might prefer to have linear development (single branch) and just manipulate ordering within that.
For me, I prefer to stack branches of related work or when there is a dependency between them, like a feature being stacked on top of a refactor to enable that feature
- Only deal with conflicts when I have to (one gets merged we're rebasing on top of it)
- Stacking of PRs, especially of unrelated work, doesn't work too well in Github
How do I stack another branch on top of an existing one?
- New branch:
git switch feature1 && git switch -c feature2and start adding commits
- Moving existing:
git stack --rebase --base feature1 --onto mainmoves
main, from off of
git rebase feature1 --onto main
How do I start a new feature?
This works like normal, just checkout the branch you want to base the feature on and start adding commits.
$ git switch feature1 $ git switch -c feature2
How do I add a commit to a parent branch in a stack?
- If this is for fixing a problem in a previous commit,
git commit --fixup <ref>and then
git-stack --rebasewill move it to where it needs to be.
- If this is to append to the parent branch, for now you'll have to use
git rebase -i
How do I stack my PRs in Github?
Currently, Github is limited to showing all commits for a branch, even if some of those commits are "owned" by another PR. We recommend only posting one PR at a time within a stack. If you really need to, you can direct your reviewers to the commits within each PR to look at. However, you will see the CI run status of top commit for each PR dependency.
When is a commit considered WIP?
If a commit summary is only
WIP or is prefixed by:
This includes the prefixes used by Gitlab
git-branch-stash is a
separate utility that is like
git stash for instead of your working tree, it
stashes what commit each of your branches points to.
git stack backs up
git branch-stashs file format to lower the risk of trying things out
Why don't you just ...?
Have an idea, we'd love to hear it!
There are probably
git operations or workflows we haven't heard of and would
welcome the opportunity to learn more.