{"id":13576621,"url":"https://github.com/VirtusLab/git-machete","last_synced_at":"2025-04-05T08:32:33.279Z","repository":{"id":37493426,"uuid":"122743101","full_name":"VirtusLab/git-machete","owner":"VirtusLab","description":"Probably the sharpest git repository organizer \u0026 rebase/merge workflow automation tool you've ever seen","archived":false,"fork":false,"pushed_at":"2024-10-29T19:07:44.000Z","size":5264,"stargazers_count":910,"open_issues_count":82,"forks_count":53,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-29T21:21:44.698Z","etag":null,"topics":["cli","git","merge","rebase"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VirtusLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-24T13:32:07.000Z","updated_at":"2024-10-27T19:40:52.000Z","dependencies_parsed_at":"2024-03-27T12:25:55.881Z","dependency_job_id":"0ba51074-53db-4c88-a954-71c48e4596f8","html_url":"https://github.com/VirtusLab/git-machete","commit_stats":{"total_commits":774,"total_committers":30,"mean_commits":25.8,"dds":0.4547803617571059,"last_synced_commit":"d52fd28f8f0652376a566cf52226030e3dd124d6"},"previous_names":[],"tags_count":166,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtusLab%2Fgit-machete","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtusLab%2Fgit-machete/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtusLab%2Fgit-machete/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtusLab%2Fgit-machete/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VirtusLab","download_url":"https://codeload.github.com/VirtusLab/git-machete/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247311852,"owners_count":20918339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","git","merge","rebase"],"created_at":"2024-08-01T15:01:12.151Z","updated_at":"2025-04-05T08:32:33.254Z","avatar_url":"https://github.com/VirtusLab.png","language":"Python","readme":"# git-machete\n\n[![homebrew formula](https://img.shields.io/homebrew/v/git-machete)](https://formulae.brew.sh/formula/git-machete)\n[![homebrew formula monthly downloads](https://img.shields.io/homebrew/installs/dm/git-machete.svg)](https://formulae.brew.sh/formula/git-machete)\n[![PyPI package](https://img.shields.io/pypi/v/git-machete.svg)](https://pypi.org/project/git-machete)\n[![PyPI package monthly downloads](https://img.shields.io/pypi/dm/git-machete.svg)](https://pypistats.org/packages/git-machete)\n[![Conda package](https://img.shields.io/conda/vn/conda-forge/git-machete.svg)](https://anaconda.org/conda-forge/git-machete)\n[![Conda downloads](https://img.shields.io/conda/dn/conda-forge/git-machete.svg)](https://anaconda.org/conda-forge/git-machete)\n\u003cbr/\u003e\n[![Read the Docs](https://readthedocs.org/projects/git-machete/badge/?version=latest)](https://git-machete.readthedocs.io/en/stable)\n[![License: MIT](https://img.shields.io/github/license/VirtusLab/git-machete)](https://github.com/VirtusLab/git-machete/blob/master/LICENSE)\n[![CircleCI](https://circleci.com/gh/VirtusLab/git-machete/tree/master.svg?style=shield)](https://app.circleci.com/pipelines/github/VirtusLab/git-machete?branch=master)\n[![codecov](https://codecov.io/gh/VirtusLab/git-machete/branch/develop/graph/badge.svg)](https://codecov.io/gh/VirtusLab/git-machete)\n\n[//]: # (These images are referenced by full URLs to ensure they render correctly on https://pypi.org/project/git-machete/)\n[//]: # (In fact, only the light-mode image is used in PyPI, the other one is cropped out when publishing the package. Still, using the same format for consistency)\n\u003cimg src=\"https://raw.githubusercontent.com/VirtusLab/git-machete/master/graphics/logo/svg/with-name.svg#gh-light-mode-only\"     style=\"width: 100%; display: block; margin-bottom: 10pt;\" /\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/VirtusLab/git-machete/master/graphics/logo/svg/with-name-dark.svg#gh-dark-mode-only\" style=\"width: 100%; display: block; margin-bottom: 10pt;\" /\u003e\n\n💪 git-machete is a robust tool that **simplifies your git workflows**.\u003cbr/\u003e\n\n🦅 The _bird's eye view_ provided by git-machete makes **merges/rebases/push/pulls hassle-free**\neven when **multiple branches** are present in the repository\n(master/develop, your topic branches, teammate's branches checked out for review, etc.).\u003cbr/\u003e\n\n🎯 Using this tool, you can maintain **small, focused, easy-to-review pull requests** with little effort.\n\n👁 A look at a `git machete status` gives an instant answer to the questions:\n* What branches are in this repository?\n* What is going to be merged (rebased/pushed/pulled) and to what?\n\n🚜 `git machete traverse` semi-automatically traverses the branches, helping you effortlessly rebase, merge, push and pull.\n\n[//]: # (The image is referenced by its full URL to ensure it renders correctly on https://pypi.org/project/git-machete/)\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/VirtusLab/git-machete/master/graphics/discover-status-traverse.gif\"\n         alt=\"git machete discover, status and traverse\" /\u003e\n\u003c/p\u003e\n\n🔌 See also [VirtusLab/git-machete-intellij-plugin](https://github.com/VirtusLab/git-machete-intellij-plugin#git-machete-intellij-plugin) \u0026mdash;\na port into a plugin for the IntelliJ Platform products, including PyCharm, WebStorm etc.\n\n\n## Install\n\nWe provide a couple of alternative ways of installation. See [PACKAGES.md](PACKAGES.md) for the full list.\n\ngit-machete requires Python \u003e= 3.6. Python 2.x is no longer supported.\n\n### Using Homebrew (macOS \u0026 most Linux distributions)\n\n```shell script\nbrew install git-machete\n```\n\n### Using pip\n\nYou need to have Python and `pip` installed from system packages.\n\n**For user-wide install:**\n```shell script\npip install --user git-machete\n```\nPlease verify that your `PATH` variable has `${HOME}/.local/bin/` included.\n\n**For system-wide install:**\n```shell script\nsudo -H pip install git-machete  # system-wide install\n```\n\n**Tip:** pass an extra `-U` flag to `pip install` to upgrade an already installed version.\n\n### Using conda\n\n```shell script\nconda install -c conda-forge git-machete\n```\n\n### Using Scoop (Windows)\n\n```shell script\nscoop install git-machete\n```\n\n### Using snap (most Linux distributions)\n\n**Tip:** check the [guide on installing snapd](https://snapcraft.io/docs/installing-snapd) if you don't have Snap support set up yet in your system.\n\n```shell script\nsudo snap install --classic git-machete\n```\n\nIt can also be installed via Ubuntu Software (simply search for `git-machete`).\n\n**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).\n\n### Using Alpine, Arch, Gentoo \u0026 other Linux distro-specific package managers\n\nCheck [Repology](https://repology.org/project/git-machete/versions) for the available distro-specific packages.\n\n### Using Nix (macOS \u0026 most Linux distributions)\n\nOn macOS and most Linux distributions, you can install via [Nix](https://nixos.org/nix):\n\n```shell script\nnix-channel --add https://nixos.org/channels/nixos-unstable unstable  # if you haven't set up any channels yet\nnix-env -i git-machete\n```\n\n**Note:** since `nixos-21.05`, `git-machete` is included in the stable channels as well.\nThe latest released version, however, is generally available in the unstable channel.\nStable channels may lag behind; see [repology](https://repology.org/project/git-machete/versions) for the current channel-package mapping.\n\n### Using Pex\n\nThe [Pex tool](https://github.com/pex-tool/pex) (short for Python EXecutable) allows you to build \"pex\" files which are executable Python environments in a single file.\n\nAssuming you have already installed the `pex` utility, you can build git-machete as a pex:\n\n```shell_script\npex git-machete -m git_machete.bin:main -o git-machete\n```\n\nThen put the produced `git-machete` file somewhere on your `PATH`.\n\n\u003cbr/\u003e\n\n## Quick start\n\n### Discover the branch layout\n\n```shell script\ncd your-repo/\ngit machete discover\n```\n\nSee and possibly edit the suggested layout of branches.\nBranch layout is always kept as a `.git/machete` text file, which can be edited directly or via `git machete edit`.\n\n### See the current repository state\n```shell script\ngit machete status --list-commits\n```\n\n**Green** edge means the given branch is **in sync** with its parent. \u003cbr/\u003e\n**Red** edge means it is **out of sync** \u0026mdash; parent has some commits that the given branch does not have. \u003cbr/\u003e\n**Gray** edge means that the branch is **merged** to its parent.\n\n### Rebase, reset to remote, push, pull all branches as needed\n```shell script\ngit machete traverse --fetch --start-from=first-root\n```\n\nPut each branch one by one in sync with its parent and remote tracking branch.\n\n### Fast-forward merge a child branch into the current branch\n```shell script\ngit machete advance\n```\n\nUseful for merging the child branch to the current branch in a linear fashion (without creating a merge commit).\n\n### GitHub \u0026 GitLab integration\n\nCheck 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: \u003cbr/\u003e\n```shell script\ngit machete github checkout-prs [--all | --by=\u003cgithub-login\u003e | --mine | \u003cPR-number-1\u003e ... \u003cPR-number-N\u003e]\ngit machete gitlab checkout-mrs [--all | --by=\u003cgitlab-login\u003e | --mine | \u003cMR-number-1\u003e ... \u003cMR-number-N\u003e]\n```\n\nCreate the PR/MR, using the upstream (parent) branch from `.git/machete` as the base: \u003cbr/\u003e\n```shell script\ngit machete github create-pr [--draft]\ngit machete gitlab create-mr [--draft]\n```\n\nThe entire chain of PRs/MRs will be posted in the PR/MR description (example for GitHub): \u003cbr/\u003e\n\n[//]: # (The image is referenced by its full URL to ensure it renders correctly on https://pypi.org/project/git-machete/)\n\u003cimg src=\"https://raw.githubusercontent.com/VirtusLab/git-machete/master/graphics/pr-chain-github-screenshot.png\"\n     alt=\"PR chain on GitHub\"\n     width=\"75%\" /\u003e\n\n**Note**: for private repositories (or side-effecting operations like `create-pr`/`create-mr` on public repositories),\na GitHub API token with `repo` access or a GitLab API token with `api` access is required.\nSee the docs for [`github`](https://git-machete.readthedocs.io/#github)\nor [`gitlab`](https://git-machete.readthedocs.io/#gitlab) for how to provide the token.\n\n### Shell completions\n\nWhen git-machete is installed via **Homebrew** (and a few other supported package managers, see [PACKAGES.md](PACKAGES.md)),\nshell completions should be installed automatically. \u003cbr/\u003e\nFor other package managers (like **pip**), or when your shell doesn't pick up the Homebrew-installed completion, use the following:\n\n#### Bash\n\nPut the following into `~/.bashrc` or `~/.bash_profile`:\n\n```shell script\neval \"$(git machete completion bash)\"  # or, if it doesn't work:\nsource \u003c(git machete completion bash)\n```\n\n#### Fish\n\nPut the following into `~/.config/fish/config.fish`:\n\n```shell script\ngit machete completion fish | source\n```\n\n#### Zsh\n\nPut the following into `~/.zshrc`:\n\n```shell script\neval \"$(git machete completion zsh)\"  # or, if it doesn't work:\nsource \u003c(git machete completion zsh)\n```\n\n\u003cbr/\u003e\n\n## FAQ\n\n#### I've run `git machete discover`... but the branch layout I see in `.git/machete` doesn't exactly match what I expected. Am I doing something wrong?\n\n[//]: # (For how to find Medium header anchors, see https://www.freecodecamp.org/news/how-to-link-to-a-specific-paragraph-in-your-medium-article-2018-table-of-contents-method-e66595fea549/)\nNo! It's all right, `discover` is based on an (imperfect)\n[heuristic](https://medium.com/virtuslab/git-machete-strikes-again-traverse-the-git-rebase-jungle-even-faster-with-v2-0-f43ebaf8abb0#0544)\nwhich usually yields branch layout close to what the user would expect.\nIt still might not be perfect and \u0026mdash; for example \u0026mdash; declare branches to be children of `main`/`develop` instead of each other.\n\nJust run [`git machete edit`](https://git-machete.readthedocs.io/en/stable/#edit) to fix the layout manually.\nIf you're working on JetBrains IDEs, you can use [git-machete IntelliJ plugin](https://github.com/VirtusLab/git-machete-intellij-plugin#git-machete-intellij-plugin)\nto have branch name completion when editing `.git/machete` file.\n\nAlso, consider [`git machete github checkout-prs` or `git machete gitlab checkout-mrs`](#github--gitlab-integration)\ninstead of `git machete discover` if you already have GitHub PRs/GitLab MRs opened.\n\n\u003cbr/\u003e\n\n#### Can I use `git merge` for dealing with stacked PRs?\n\nThere are two commonly used ways to put a branch back in sync with its base (parent) branch:\n1. rebase the branch onto its base branch\n2. merge the base branch into the branch\n\nWhile git-machete supports merging base branch (like `main`) to update the branch\n([`git machete traverse --merge`](https://git-machete.readthedocs.io/en/stable/#traverse)),\nthis approach **works poorly with stacked PRs**.\nYou might end up with a very tangled history very quickly, and a non-trivial sequence of `git cherry-pick`s might be needed to restore order.\n\nThat is why we recommend using rebase over merge for stacked PRs.\nHowever, we still recommend using merge for the narrow case of [backporting hotfixes](https://slides.com/plipski/git-machete/#/11).\n\n\u003cbr/\u003e\n\n#### In what order should I merge stacked PRs?\n\nWe recommend merging PRs from the top-most (closest to the root branch, typically `main` or `master`).\nIn other words, PR should only be merged when its base is a root branch.\n\nThis way, you don't end up with a big-ball-of-code PR at the end.\nAvoid such balls is one of the main reasons for opening small PRs in the first place.\n\n\u003cbr/\u003e\n\n#### Sometimes when I run `update` or `traverse`, too many commits are taken into the rebase... how to fix that?\n\nContrary to the popular misconception, git doesn't have a notion of\n[\"commits belonging to a branch\"](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell).\nA branch is just a movable reference to a commit.\n\nThis makes it hard in general case to determine the range of commits that form the \"unique history\" of the given branch.\nThere's an entire algorithm in git-machete for determining the\n[_fork point_](https://medium.com/virtuslab/make-your-way-through-the-git-rebase-jungle-with-git-machete-e2ed4dbacd02#1ac9)\nof the branch (i.e. the place after which the unique history of the branch starts).\n\nOne thing that you can do to help fork-point algorithm in its job,\nis to **not delete** local branches instantly after they're merged or discarded.\nThey (or specifically, their [reflogs](https://virtuslab.github.io/tips/#git/git-reflog)) will be still useful for a while\nto determine fork points for other branches (and thus, the range of commits taken into rebase).\n\nAlso, you can always override fork point for a branch explicitly\nwith [`git machete fork-point --override-to...`](https://git-machete.readthedocs.io/#fork-point) command.\n\n\u003cbr/\u003e\n\n## Reference\n\nFind the docs at [Read the Docs](https://git-machete.readthedocs.io/).\nYou can also check `git machete help` and `git machete help \u003ccommand\u003e`.\n\nFor the excellent overview for the reasons to use small \u0026 stacked PRs,\nsee [Ben Congdon](https://github.com/bcongdon)'s [blog post](https://benjamincongdon.me/blog/2022/07/17/In-Praise-of-Stacked-PRs/).\n\nTake a look at git-machete\n[reference blog post](https://medium.com/virtuslab/make-your-way-through-the-git-rebase-jungle-with-git-machete-e2ed4dbacd02)\nfor a guide on how to use the tool.\n\nThe more advanced features like automated traversal, upstream inference and tree discovery are described in the\n[second part of the series](https://medium.com/virtuslab/git-machete-strikes-again-traverse-the-git-rebase-jungle-even-faster-with-v2-0-f43ebaf8abb0).\n\n\u003cbr/\u003e\n\n\n## Git compatibility\n\ngit-machete (since version 2.13.0) is compatible with git \u003e= 1.8.0.\n\n\u003cbr/\u003e\n\n\n## Contributions\n\nContributions are welcome! See [contributing guidelines](CONTRIBUTING.md) for details.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVirtusLab%2Fgit-machete","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVirtusLab%2Fgit-machete","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVirtusLab%2Fgit-machete/lists"}