Contributing

May 19, 2026 · View on GitHub

PyCharm setup

Make sure the following bundled plugins are enabled:

Docker
Git
Markdown
Ini
IntelliLang (for language injections, e.g. Markdown/shell scripts in YAML)
ReStructuredText
Shell Script (also: agree to enable Shellcheck when asked)
YAML

Optionally, you can also install the following non-bundled plugins from Marketplace:

Git setup

From the main project folder, run the following commands:

ln -s ../../hook_samples/machete-status-branch .git/hooks/machete-status-branch
ln -s ../../hook_samples/post-commit .git/hooks/post-commit
ln -s ../../ci/checks/run-all-checks.sh .git/hooks/pre-commit

Install fish and shellcheck for run-all-checks.sh to pass successfully.

Run tests locally

tox -e py

To display rich diff when tests fail, use

tox -e py -- -k github -vv  # also, use -k for tests whose names contain a specific string

To display full operands in failed assertions (rather than just diffs), use

tox -e py -- -k "hub or lab" --full-operands  # logical expressions are also allowed in -k

Install locally for development purposes

To execute git-machete commands in terminal using current branch implementation, you must first have a virtual environment. You can create one named venv by executing tox -e venv or use existing environment (need to install requirements from requirements/testenv.txt). You have to activate the environment, for the venv environment run source .tox/venv/bin/activate from git-machete root directory. Lastly, install git-machete in development mode with pip install --editable . --- codebase can now be edited in-place without reinstallation.

Terminal: user-wide installation

Use pip install --user .. Locate the installed package with pip show -f git-machete --- you'll see something like:

<...metadata...>
Location: /Users/pawel_lipski/Library/Python/3.9/lib/python/site-packages
Requires:
Required-by:
Files:
  <...files...>
  ../../../bin/git-machete
  <...files...>

Compound the Location with the relative path to bin/git-machete launcher script to locate the directory where the launcher script is located. In the above macOS example, it'll be $HOME/Library/Python/3.9/bin. On Linuxes, it's likely to be $HOME/.local/bin instead. Add this directory to PATH. Re-installation will be needed after a modification, as --editable and --user don't seem to work together.

IDE (PyCharm): venv

To execute tests in IDE (e.g. PyCharm -> right-clicking on the test file or clicking the green triangle on the left of the test case name), you must first have a virtual environment. You can create one named venv by executing tox -e venv or use existing environment (but then you need to install requirements from requirements/testenv.txt). Lastly, setup python interpreter for your project in the IDE, e.g. .tox/venv/bin/python.

To run/debug git-machete commands directly in IDE you need to create custom Run/Debug Configuration: set Script Path e.g. to git_machete/cli.py and provide command as Parameters.

Generate sandbox repositories

Run scripts/setup-sandbox script to set up a test repo under ~/machete-sandbox with a remote in ~/machete-sandbox-remote.

Regenerate the GIFs in README.md

For discover-status-traverse.gif:

Install asciinema, agg (at least v1.4.1), and sponge. On macOS, just brew install asciinema agg sponge should be enough.
Run ./scripts/generate-asciinema-gif img/discover-status-traverse.gif.

For go-interactive.gif — on macOS:

Install ffmpeg and gifsicle (brew install ffmpeg gifsicle)
Press Cmd+Shift+5 and select the portion of the screen to record.
Press the Capture screen portion button.
When done, finish with Cmd+Ctrl+Esc.
Find the screencast in ~/Desktop.
Run ffmpeg -i ~/Desktop/"Screen Recording <DATE>.mov" -pix_fmt rgb8 -r 10 output.gif && gifsicle -O3 output.gif -o output.gif

Versioning

This tool is semantically versioned with respect to all of the following:

Python and Git version compatibility
command-line interface (commands and their options)
format of its specific files (like .git/machete but also e.g. .git/info/description and ~/.github-token)
hooks and their command-line interface
output format of plumbing commands
accepted environment variables

Output format of any non-plumbing command can change in a non-backward-compatible manner even between patch-level updates.

CI Docker setup reference

FAQ about Pull Requests

What is the proper base for pull request?

Please set the base of pull request to develop branch. Current branch protection rules on GitHub only allow to merge develop or hotfix/* branches into master.

Who closes GitHub comments? Author of changes, reviewer or initiator of the conversation?

It makes sense to close comment:

If the comment was trivial and was addressed as suggested by the reviewer, then it is enough for the PR author to simply Resolve the thread and that's it.
If the comment was not trivial and/or for some reason the PR author believes that the comment should not be addressed as suggested by the reviewer, then it is best to leave the thread open after replying; then the reviewer can press Resolve once they have decided that the matter is cleared.

Create release PR from develop into master.
Verify that all checks have passed.

Merge develop into master and push to remote repository using console (not using GitHub Merge Button):

  git checkout develop
  git pull origin develop
  git checkout master
  git pull origin master
  git merge --ff-only develop
  git push origin master

Verify that changes you made in files holding blogs content (if any) are reflected in the corresponding medium articles:
If not, please apply changes on Medium to keep consistency. Since Medium does not offer conversion directly from Markdown, copy the formatted blog text from a GitHub and paste it into the Medium rich text editor. Once the changes are applied, make sure that the <p>/<h1> ids referenced from links in README did not change (or are updated accordingly).