Package: git-machete
git-machete💪 git-machete is a robust tool thatsimplifies your git workflows.🦅 Thebird's eye viewprovided by git-machete makesmerges/rebases/push/pulls hassle-freeeven whenmultiple branchesare present in the repository
(master/develop, your topic branches, teammate's branches checked out for review, etc.).🎯 Using this tool, you can maintainsmall, focused, easy-to-review pull requestswith little effort.👁 A look at agit machete statusgives an instant answer to the questions:What branches are in this repository?What is going to be merged (rebased/pushed/pulled) and to what?🚜git machete traversesemi-automatically traverses the branches, helping you effortlessly rebase, merge, push and pull.🔌 See alsoVirtusLab/git-machete-intellij-plugin—
a port into a plugin for the IntelliJ Platform products, including PyCharm, WebStorm etc.InstallWe provide a couple of alternative ways of installation. SeePACKAGES.mdfor the full list.git-machete requires Python >= 3.6. Python 2.x is no longer supported.Using Homebrew (macOS & most Linux distributions)brewinstallgit-macheteUsing pip with sudo (system-wide install)You need to have Python andpipinstalled from system packages.sudo-Hpipinstallgit-macheteTip:pass an extra-Uflag topip installto upgrade an already installed version.Using pip without sudo (user-wide install)You need to have Python andpipinstalled from system packages.pipinstall--usergit-machetePlease verify that yourPATHvariable has${HOME}/.local/bin/included.Tip:pass an extra-Uflag topip installto upgrade an already installed version.Using condacondainstall-cconda-forgegit-macheteUsing snap (most Linux distributions)Tip:check theguide on installing snapdif you don't have Snap support set up yet in your system.sudosnapinstall--classicgit-macheteIt can also be installed via Ubuntu Software (simply search forgit-machete).Note:classic confinement is necessary to ensure access to the editor installed in the system (to edit e.g. .git/machete file or rebase TODO list).Using apt-get via PPA (Ubuntu)Tip:runsudo apt-get install -y software-properties-commonfirst ifadd-apt-repositoryis not available on your system.sudoadd-apt-repositoryppa:virtuslab/git-machete
sudoapt-getupdate
sudoapt-getinstall-ypython3-git-macheteUsing rpm (Fedora/RHEL/CentOS/openSUSE...)Download the rpm package from thelatest releaseand install either by opening it in your desktop environment or withrpm -i git-machete-*.noarch.rpm.Using Alpine, Arch, Gentoo & other Linux distro-specific package managersCheckRepologyfor the available distro-specific packages.Using Nix (macOS & most Linux distributions)On macOS and most Linux distributions, you can install viaNix:nix-channel--addhttps://nixos.org/channels/nixos-unstableunstable# if you haven't set up any channels yetnix-env-igit-macheteNote:sincenixos-21.05,git-macheteis included in the stable channels as well.
The latest released version, however, is generally available in the unstable channel.
Stable channels may lag behind; seerepologyfor the current channel-package mapping.Quick startDiscover the branch layoutcdyour-repo/
gitmachetediscoverSee and possibly edit the suggested layout of branches.
Branch layout is always kept as a.git/machetetext file, which can be edited directly or viagit machete edit.See the current repository stategitmachetestatus--list-commitsGreenedge means the given branch isin syncwith its parent.Rededge means it isout of sync— parent has some commits that the given branch does not have.Grayedge means that the branch ismergedto its parent.Rebase, reset to remote, push, pull all branches as neededgitmachetetraverse--fetch--start-from=first-rootPut each branch one by one in sync with its parent and remote tracking branch.Fast-forward merge a child branch into the current branchgitmacheteadvanceUseful for merging the child branch to the current branch in a linear fashion (without creating a merge commit).GitHub integrationCheck out the given PRs into local branches, also traverse chain of pull requests upwards, adding branches one by one to git-machete and check them out locally as well:gitmachetegithubcheckout-prs[--all|--by=<github-login>|--mine|<PR-number-1>...<PR-number-N>]Create the PR, using the upstream (parent) branch from.git/macheteas the base:gitmachetegithubcreate-pr[--draft]The entire chain of PRs will be posted in the PR description:Note: for private repositories (or side-effecting operations likecreate-pron public repositories),
a GitHub API token withrepoaccess is required.
See thedocsfor how to provide the token.Shell completionsWhen git-machete is installed viaHomebrew(and a few other supported package managers, seePACKAGES.md),
shell completions should be installed automatically.For other package managers (likepip), or when your shell doesn't pick up the Homebrew-installed completion, use the following:BashPut the following into~/.bashrcor~/.bash_profile:eval"$(gitmachetecompletionbash)"# or, if it doesn't work:source<(gitmachetecompletionbash)FishPut the following into~/.config/fish/config.fish:gitmachetecompletionfish|sourceZshPut the following into~/.zshrc:eval"$(gitmachetecompletionzsh)"# or, if it doesn't work:source<(gitmachetecompletionzsh)FAQI've rungit machete discover... but the branch layout I see in.git/machetedoesn't exactly match what I expected. Am I doing something wrong?No! It's all right,discoveris based on an (imperfect)heuristicwhich usually yields branch layout close to what the user would expect.
It still might not be perfect and — for example — declare branches to be children ofmain/developinstead of each other.Just rungit machete editto fix the layout manually.
If you're working on JetBrains IDEs, you can usegit-machete IntelliJ pluginto have branch name completion when editing.git/machetefile.Also, considergit machete github checkout-prsinstead ofgit machete discoverif you already have GitHub PRs opened.Can I usegit mergefor dealing with stacked PRs?There are two commonly used ways to put a branch back in sync with its base (parent) branch:rebase the branch onto its base branchmerge the base branch into the branchWhile git-machete supports merging base branch (likemain) to update the branch
(git machete traverse --merge),
this approachworks poorly with stacked PRs.
You might end up with a very tangled history very quickly, and a non-trivial sequence ofgit cherry-picks might be needed to restore order.That is why we recommend using rebase over merge for stacked PRs.
However, we still recommend using merge for the narrow case ofbackporting hotfixes.Sometimes when I runupdateortraverse, too many commits are taken into the rebase... how to fix that?Contrary to the popular misconception, git doesn't have a notion of"commits belonging to a branch".
A branch is just a movable reference to a commit.This makes it hard in general case to determine the range of commits that form the "unique history" of the given branch.
There's an entire algorithm in git-machete for determining thefork pointof the branch (i.e. the place after which the unique history of the branch starts).One thing that you can do to help fork-point algorithm in its job,
is tonot deletelocal branches instantly after they're merged or discarded.
They (or specifically, theirreflogs) will be still useful for a while
to determine fork points for other branches (and thus, the range of commits taken into rebase).Also, you can always override fork point for a branch explicitly
withgit machete fork-point --override-to...command.ReferenceFind the docs atRead the Docs.
You can also checkgit machete helpandgit machete help <command>.For the excellent overview for the reasons to use small & stacked PRs,
seeBen Congdon'sblog post.Take a look at git-machetereference blog postfor a guide on how to use the tool.The more advanced features like automated traversal, upstream inference and tree discovery are described in thesecond part of the series.Git compatibilitygit-machete (since version 2.13.0) is compatible with git >= 1.8.0.ContributionsContributions are welcome! Seecontributing guidelinesfor details.