# 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:
<img width="350" alt="linear_history" src="https://user-images.githubusercontent.com/464795/115330193-947c3600-a161-11eb-9e2b-888fa04f7e34.png">
**Further Reading & Context**
- [A Tidy Linear Git History](https://www.bitsnbites.eu/a-tidy-linear-git-history/)
- [Avoid Messy Git History](https://dev.to/bladesensei/avoid-messy-git-history-3g26)
- [A Git Workflow for Agile Teams](http://reinh.com/blog/2009/03/02/a-git-workflow-for-agile-teams.html)
- [Git Rebase Tutorial](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase)
# 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
```ini
[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
1. Run `sudo -H pip3 install git-pr-linear-merge`
1. 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](https://www.python.org/dev/peps/pep-0440/)
### 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/*
```
Raw data
{
"_id": null,
"home_page": "https://github.com/waldobronchart/git-pr-linear-merge",
"name": "git-pr-linear-merge",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "github,pull request,linear merge,linear history,semi-linear merge",
"author": "Waldo Bronchart",
"author_email": "wbronchart@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bd/2d/2686c98f42e418b0b35306e45ee4424e64a3d4634f44b7981b2835da19f2/git-pr-linear-merge-1.1.1.tar.gz",
"platform": null,
"description": "# git-pr-linear-merge\n\nA command line utility to list and merge GitHub pull requests while maintaining linear history.\n\nTo 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:\n\n<img width=\"350\" alt=\"linear_history\" src=\"https://user-images.githubusercontent.com/464795/115330193-947c3600-a161-11eb-9e2b-888fa04f7e34.png\">\n\n**Further Reading & Context**\n- [A Tidy Linear Git History](https://www.bitsnbites.eu/a-tidy-linear-git-history/)\n- [Avoid Messy Git History](https://dev.to/bladesensei/avoid-messy-git-history-3g26)\n- [A Git Workflow for Agile Teams](http://reinh.com/blog/2009/03/02/a-git-workflow-for-agile-teams.html)\n- [Git Rebase Tutorial](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase)\n\n# Usage\n\n## Installing\n\nPython3.6 or above is required. You can install this package by running the following command:\n```\npip3 install git-pr-linear-merge\n```\n\nTo upgrade to the latest version:\n```\npip3 install --upgrade git-pr-linear-merge\n```\n\n## How To Use\n\nGet help: `git pr -h`\n\nThe first time you run this script, you will be asked to authenticate with Github.\n\n### List Command\n\nList all open pull requests: `git pr list`, or list only yours with `git pr list --mine`\n```\n # Title Branch\n---- ------------------------------------------------------------ -------------------------------\n5811 Fix various bugs with video player fix/kevin-video-player-bugs\n5812 Fix highlight being stuck when gallery frame is deactivated fix/kevin-highlightable-view\n...\n```\n\n### Merge Command\n\nMerge a pull request: `git pr merge NUMBER`\n\n\n\n### Squash Command\n\nSquash a pull request: `git pr squash NUMBER`\n\nThe 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.\n\nHere's what the history looks like when you use `squash` vs `merge`.\n\n\n\n\n## Repo configuration\n\nAdd a `.linmergerc` config file to the repo root directory to customize behaviour to your teams preference.\n\nBelow are all the options\n```ini\n[merge]\n# Commit message format vars: TITLE, NUMBER, AUTHOR_NAME, AUTHOR_USERNAME\nmerge_msg_format = Merge: {TITLE} (#{NUMBER})\n# Enable single-commit pulls to be squashed instead of merging, even when explicitly using the merge command\nalways_squash_single_commit_pulls = True\n\n[squash]\nsquash_msg_format = {TITLE} (#{NUMBER})\n# Enable usage of the `git pr squash` command\nsquash_cmd_enabled = True\n```\n\n## Troubleshooting\n\n- You see \"git: pr is not a git command\"\n 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\n 1. Run `sudo -H pip3 install git-pr-linear-merge`\n 1. 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\n\n# Development\n\nThis section explains how to setup the dev environment and update the package\n\n## Environment setup\n\nTo install all the python packages that this package needs, run this once: `pipenv install`\n\nThen, to activate the environment in your terminal, run: `pipenv shell`\n\n## Running Locally\n\nWith 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.\n```\npython ~/path/to/your/local/checkout/git-pr.py\n```\n\n## Updating the package\n\nMake sure to bump the version number with updates according to [PEP 440](https://www.python.org/dev/peps/pep-0440/)\n\n### Publish and Install from TestPyPi\n\nBefore publishing for real, you can test a package by publishing it to TestPyPi\n\nPublishing:\n```\npipenv sync\npipenv install --dev\npipenv shell\nrm -rf dist\nrm -rf build\npython -m build\ntwine upload --repository testpypi dist/*\n```\n\nInstalling:\n```\npython3 -m pip install --upgrade --index-url https://test.pypi.org/simple/ git-pr-linear-merge\n```\n\n### Publish\n\n```\npipenv shell\nrm -rf dist\nrm -rf build\npython -m build\ntwine upload dist/*\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A command line utility to list and merge GitHub pull requests while maintaining linear history",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/waldobronchart/git-pr-linear-merge/issues",
"Homepage": "https://github.com/waldobronchart/git-pr-linear-merge",
"Source": "https://github.com/waldobronchart/git-pr-linear-merge"
},
"split_keywords": [
"github",
"pull request",
"linear merge",
"linear history",
"semi-linear merge"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2ffc74f1789750eb7c71f32be329612b6770cd22e0c85446a09ffe46c7465620",
"md5": "eae9a32892880d31b24fb0b3468823c6",
"sha256": "0556330f52d68ecc453f455d3ff0b93c76d737610d39fca1dfa2cba54e029e8e"
},
"downloads": -1,
"filename": "git_pr_linear_merge-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eae9a32892880d31b24fb0b3468823c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 12305,
"upload_time": "2023-07-04T18:18:59",
"upload_time_iso_8601": "2023-07-04T18:18:59.782901Z",
"url": "https://files.pythonhosted.org/packages/2f/fc/74f1789750eb7c71f32be329612b6770cd22e0c85446a09ffe46c7465620/git_pr_linear_merge-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bd2d2686c98f42e418b0b35306e45ee4424e64a3d4634f44b7981b2835da19f2",
"md5": "1725faa40d509e7730c73d4dc450658c",
"sha256": "b61587e506fc872130e00fd20ff835f49682a97d1eec93dda6bded2516a043bd"
},
"downloads": -1,
"filename": "git-pr-linear-merge-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1725faa40d509e7730c73d4dc450658c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 13117,
"upload_time": "2023-07-04T18:19:01",
"upload_time_iso_8601": "2023-07-04T18:19:01.588384Z",
"url": "https://files.pythonhosted.org/packages/bd/2d/2686c98f42e418b0b35306e45ee4424e64a3d4634f44b7981b2835da19f2/git-pr-linear-merge-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-04 18:19:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "waldobronchart",
"github_project": "git-pr-linear-merge",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "git-pr-linear-merge"
}
JSON
