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¹. In any case, you commit directly to master as you go², 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³ 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

1. Add all of your commits to a single branch. I recommend using the repository's default branch.

2. 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:

1. turn the set of commits addressing each issue into its own branch,
2. push that branch, and
3. 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.

Footnotes

1. https://www.adamtal.me/2019/05/first-make-the-change-easy-then-make-the-easy-change ↩

2. https://drewdevault.com/2020/04/06/My-weird-branchless-git-workflow.html ↩

3. https://git-scm.com/docs/git-interpret-trailers ↩