git-pr-linear-merge

A command line utility to list and merge GitHub pull requests while maintaining linear history.

To maintain linear history, a pull request branch is rebased on top of its base, before merging. This creates a linear history like in this diagram:

Further Reading & Context

• A Tidy Linear Git History
• Avoid Messy Git History
• A Git Workflow for Agile Teams
• Git Rebase Tutorial

Usage

Installing

Python3.6 or above is required. You can install this package by running the following command:

pip3 install git-pr-linear-merge

To upgrade to the latest version:

pip3 install --upgrade git-pr-linear-merge

How To Use

Get help: git pr -h

The first time you run this script, you will be asked to authenticate with Github.

List Command

List all open pull requests: git pr list, or list only yours with git pr list --mine

   #  Title                                                         Branch
----  ------------------------------------------------------------  -------------------------------
5811  Fix various bugs with video player                            fix/kevin-video-player-bugs
5812  Fix highlight being stuck when gallery frame is deactivated   fix/kevin-highlightable-view
...

Merge Command

Merge a pull request: git pr merge NUMBER

Squash Command

Squash a pull request: git pr squash NUMBER

The squash command collapses all commits from the pull branch into a single commit and puts that commit straight onto the base branch without doing an explicit merge.

Here's what the history looks like when you use squash vs merge.

Repo configuration

Add a .linmergerc config file to the repo root directory to customize behaviour to your teams preference.

Below are all the options

[merge]
# Commit message format vars: TITLE, NUMBER, AUTHOR_NAME, AUTHOR_USERNAME
merge_msg_format = Merge: {TITLE} (#{NUMBER})
# Enable single-commit pulls to be squashed instead of merging, even when explicitly using the merge command
always_squash_single_commit_pulls = True

[squash]
squash_msg_format = {TITLE} (#{NUMBER})
# Enable usage of the `git pr squash` command
squash_cmd_enabled = True

Troubleshooting

• You see "git: pr is not a git command"
  1. Run sudo pip3 install git-pr-linear-merge and see if you receive a yellow warning message indicating ..../Library/Caches/pip is not writable by the current user. This indicates the installation has not completed successfully due to incorrect write permissions
  2. Run sudo -H pip3 install git-pr-linear-merge
  3. If the error still persists, make sure you have write access to ~/Library/Python/3.X/bin. Run sudo -H pip3 install git-pr-linear-merge again if you changed any write permissions

Development

This section explains how to setup the dev environment and update the package

Environment setup

To install all the python packages that this package needs, run this once: pipenv install

Then, to activate the environment in your terminal, run: pipenv shell

Running Locally

With the environment setup through the previous step, you can run git pr using your local code by running the git-pr.py script in the root directory of this repo.

python ~/path/to/your/local/checkout/git-pr.py

Updating the package

Make sure to bump the version number with updates according to PEP 440

Publish and Install from TestPyPi

Before publishing for real, you can test a package by publishing it to TestPyPi

Publishing:

pipenv sync
pipenv install --dev
pipenv shell
rm -rf dist
rm -rf build
python -m build
twine upload --repository testpypi dist/*

Installing:

python3 -m pip install --upgrade --index-url https://test.pypi.org/simple/ git-pr-linear-merge

Publish

pipenv shell
rm -rf dist
rm -rf build
python -m build
twine upload dist/*