git-machete: A Branch Organizer That Automates the Merge Stack

A Map of the Branches You Are Working On

git-machete presents itself as probably the sharpest git repository organizer and rebase or merge workflow automation tool you have ever seen, and the project description is a fair summary of the problem it solves.

The problem is that a real repository holds more than one branch at a time. There is the base branch, master or develop, there are your own topic branches, and there are branches a colleague has checked out for review. When several of those need to be rebased onto the base branch, merged into it, pushed and then pulled, the order matters and the bookkeeping is the part that eats an afternoon.

The tool's answer is a bird's eye view. The status command gives an instant answer to two questions: what branches are in this repository, and what is going to be merged, rebased, pushed or pulled and to what.

The result is that you can maintain small, focused, easy to review pull requests with little effort, which is the stated goal. The tool does not make your pull requests smaller, it makes the stack of them tractable.

Three Edge Colours Encode Three Relationships

The status output is a graph, and the graph uses colour to say what each branch's relationship with its parent is. There are three states and each one means something specific.

A green edge means the given branch is in sync with its parent. A red edge means it is out of sync, so the parent has some commits that the given branch does not have. A gray edge means that the branch is merged to its parent.

That is the core of the tool, and it is worth understanding the semantics rather than the colours. In sync means you could merge or rebase that branch today without losing anything. Out of sync means the parent has moved on, which is the case that needs a rebase. Merged means the work is already in the parent, which is the case where the branch can be deleted.

The command that shows this is git machete status with the --list-commits option, and the README describes the output as a look that gives an instant answer, which is the right standard for a status command.

discover Builds the Layout and the File You Own

The starting point is a command that works out the branch structure for you, and a file that holds the result.

You change into the repository and run git machete discover, which suggests a layout of the branches, and you then review and possibly edit it. The layout is always kept as a .git/machete text file, which can be edited directly or via the git machete edit command.

The fact that the layout is a plain text file inside the .git directory is the most important design decision in the tool. It is not stored in a database, it is not stored in a config directory that needs its own format, and it is not a binary blob. You can read it, you can diff it, you can put it under version control if you want a shared layout for a team, and you can comment in it.

The discover command being a suggestion rather than an order matters too. A tool that assumed the layout would be wrong in the cases where a repository has an unusual structure, and a tool that wrote your assumptions into a file you did not read would be worse. Here the tool proposes and you decide, and the file is the record of the decision.

traverse Walks the Stack for You

The second headline command is traverse, which semi-automatically traverses the branches, helping you effortlessly rebase, merge, push and pull.

The word semi-automatically is the honest part. The tool knows the order of operations, because the layout file says which branch sits on which, and it can run the appropriate git command for each step in the right sequence. What it does not know is whether you want to rebase or merge, or whether a particular push should wait for a review, so it asks.

That is where the branch layout pays for itself. Rebasing four topic branches onto a base branch, in the right order, and then pushing them, is four commands that are easy to do in the wrong order. The layout removes the need to remember the order and lets the tool do the mechanical part.

The animation in the README shows the sequence of the discover, status and traverse commands working together on a real repository, and the point of the animation is that the three commands are one workflow rather than three separate features.

Seven Ways to Install, and Why Each One Is There

The installation section is long because the project supports a lot of platforms, and the package list is in a separate file, PACKAGES.md, with the full set.

The requirement is Python 3.6 or later, and Python 2 is no longer supported. Then there is a route for each kind of user:

```shell script brew install git-machete pip install --user git-machete conda install -c conda-forge git-machete scoop install git-machete sudo snap install --classic git-machete ```

Homebrew covers macOS and most Linux distributions, pip covers everyone else, conda and Scoop have their own channels, and snap is for most Linux distributions. pip works either user-wide with pip install --user git-machete, where you need ${HOME}/.local/bin/ on your PATH, or system-wide with sudo -H pip install git-machete, and the tip is to pass an extra -U flag to upgrade an installed version.

Conda is conda install -c conda-forge git-machete. Scoop covers Windows with scoop install git-machete. Snap covers most Linux distributions with sudo snap install --classic git-machete, and there is a note that classic confinement is necessary to ensure access to the editor installed in the system, for editing the.git/machete file or the rebase TODO list, and that it can also be installed via Ubuntu Software. Repology is the pointer for the remaining distributions, Alpine, Arch and Gentoo among them.

Nix has its own instructions, adding the unstable channel and installing with nix-env, with the note that since nixos-21.05 the package is in the stable channels as well, that the latest released version is generally available in the unstable channel, and that stable channels may lag behind.

The last option is unusual. Pex, short for Python EXecutable, builds an executable Python environment in a single file, and git-machete is built with pex git-machete -m git_machete.bin:main -o git-machete, after which the produced file goes on your PATH. That is a single file with no installation, which is useful on a machine where you cannot install anything.

The Interactive Picker and Its Windows Gap

The go command is the interactive part of the tool, and it is the one with a platform limitation.

git machete go opens an interactive interface where you select a branch to check out using arrow keys and Enter to select. The README includes an animation of the PR chain on GitHub, which is the case where the tool is most useful, because a stack of pull requests is exactly the situation where picking the right branch by name is tedious.

The limitation is stated in a note: interactive mode is not supported on Windows yet. The reason is not given, and it is a reasonable guess that the terminal handling on Windows differs enough to make the picker unreliable, but the documentation does not say so, so the reason should not be assumed.

The pragmatic consequence is that a Windows user gets the rest of the tool, which is the majority of it, since status, discover, traverse and edit are all non-interactive, and loses the picker. Since Windows support is otherwise first class, with a Scoop package and a note in the repository, the gap is about the one command that needs a terminal that can render a menu reliably.

The Package Layout, the Docs and the Release Cadence

The repository is a mature Python project with the usual pieces and a few that are specific to it.

The source lives in git_machete/, and the setup.py lists the packaged subpackages, git_machete, git_machete.client and git_machete.utils, alongside completion for the shell completions and docs/man for the manual pages. The console entry point is git-machete mapped to git_machete.bin:main, and the package requires Python 3.6 or later but below 4. The classifiers mark it as Production and Stable, and the comment in the setup file notes that this is a pure-Python but not universal wheel.

Around the source there is docs/ with the tutorial the README links to, tests/, completion/, skills/, hook_samples/, snap/ for the snap packaging, ci/, scripts/, requirements/, flake8/ and a mypy.ini, with tox.ini as the test runner. There is a CHANGELOG in the form of RELEASE_NOTES.md, a PACKAGES.md listing the distributions, an AGENTS.md at the root and a.readthedocs.yaml for the published documentation, plus a blogs/ directory.

The release cadence is steady, with v3.46.1 on 2026-10-03, v3.46.0 on 2026-09-21 and v3.45.0 on 2026-09-05, and the default branch is develop, which tells you the development branch is where the work happens and the tags come off it. The last push was on 2026-10-11.

There is also a companion project, the git-machete IntelliJ plugin, a port into a plugin for the IntelliJ Platform products including PyCharm and WebStorm, so the same layout model is available inside an IDE.

Editorial conclusion

git-machete fits a developer whose repository has accumulated several topic branches, a base branch and a few colleague branches under review, and who wants the order of operations decided by a file rather than by memory. It is a poor fit if you work on one branch at a time, since the whole value is in the relationship between branches, and it is a poor fit if you need the interactive branch picker, since interactive mode is not supported on Windows yet. Before adopting it, read the branch layout file after running discover, because the tool is only as good as that description, and remember that the tool describes and drives git rather than replacing it, since every operation it performs is one you could run by hand. The project is MIT licensed, the current release is v3.46.1 from 2026-10-03, and the last push was on 2026-10-11.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. VirtusLab/git-machete on GitHub