348 releases
new 0.10.242 | Dec 11, 2024 |
---|---|
0.10.240 | Nov 17, 2024 |
0.10.209 | Jul 29, 2024 |
0.10.185 | Mar 25, 2024 |
0.7.27 | Nov 22, 2022 |
#28 in Command line utilities
705 downloads per month
91KB
2K
SLoC
git disjoint
git-disjoint automates an optimal git workflow for PR authors and reviewers by grouping commits by issue into GitHub PRs.
This encourages the submission of small, independent PRs, minimizing cognitive load on reviewers, maximizing the utility of your git history, and keeping cycle time low.
Elevator Pitch
You're working on a feature. As you work, you create some commits that don't directly implement your feature. Maybe you improve some documentation, fix a minor bug, or first refactor to make the change easy, before making the easy change^1. In any case, you commit directly to master as you go^2, because you want each change to persist in your development environment, even before it's gone through code review and landed upstream.
When you come to a natural stopping point, you are ready to ship several commits. Each commit is atomic, relating to just one topic. It comes with a detailed commit message referencing an issue in your work tracker, passing unit tests, and documentation. You don't want to shove all these changes into a single PR, because they deal with orthogonal concerns. You trust your team to contribute quality code reviews, and iterating on one changeset shouldn't delay unrelated changes from merging.
Instead of creating a PR directly from your master, or manually moving commits into separate branches, do this:
git disjoint
git-disjoint will identify which commits relate to the same issue, batch these commits into a new branch, and create a PR.
How does it work?
git-disjoint looks for trailers^3 in each commit message to determine which issue a commit relates to. By default, it creates one PR for each issue and associates the PR to an existing issue in your work tracker.
When a PR merges, your next git pull
effectively moves upstream's master from
behind your local commits to ahead of them.
Supported Integrations
git-disjoint adds value to your workflow if you:
- use a work tracker (supports Jira and GitHub Issues)
- use GitHub and Pull Requests
Requirements
You need a GitHub personal access token with repo
scope. Either export this
as the GITHUB_TOKEN
environment variable or pass it to git-disjoint with
the --token
option.
Install
From GitHub releases
The easiest way to install git-disjoint is to download a release compatible with your OS and architecture from the Releases page.
Alternatively, install git-disjoint with one of the following package managers:
Repository | Command |
---|---|
Cargo | cargo +nightly install git-disjoint |
Cargo binstall | cargo binstall git-disjoint |
Nix | nix profile install github:EricCrosson/git-disjoint |
Use
Make commits
-
Add all of your commits to a single branch. I recommend using the repository's default branch.
-
In each commit message, include a reference to the relevant issue.
For example, use the Jira automation format:
Ticket: COOL-123
or
Closes Ticket: COOL-123
Or use the GitHub format:
Closes #123
Open PRs
When you're ready to:
- turn the set of commits addressing each issue into its own branch,
- push that branch, and
- create a draft PR,
run git disjoint
.
How-to Guide
How do I ignore certain commits?
To ignore commits associated with an issue, use the --choose
flag. This will
open a menu where you can select the issues to create PRs for.
How do I use git-disjoint on commits without an associated issue?
Use the --all
flag to include commits without a recognized trailer.
Dependencies
~24–39MB
~686K SLoC