git-lint-branch git-lint-branch is a linter for git branch histories.

As contributors, use this tool to check your branch history against common mistakes that annoy maintainers - and make that perfect pull request.

As maintainers, expect quality pull requests that satisfy rules you set, decreasing the time it takes to merge in those changes and release that new feature. Setup your CI to fail in case something's seriously wrong with a branch's history.

What inspired us

As a contributor, making that first pull request is hard. Going through pages and pages of super picky contributing guidelines and making sure they are adhered to often seems more overwhelming than the 5 lines of code changes. Not a surprise that many people submit PRs with messy branch histories, requiring the maintainer to spend time and effort cleaning it up.

This project intends to fix this. It is a utility that can be run over a branch before submitting the pull request, and it'll point out any commits that seem out of place: diffs that are too large, commit messages that could've been phrased better or merge-commits that shouldn't be. The feedback pinpoints exactly what and where the problem is, how to fix it, and is tailored to the guidelines followed by that particular project. While you cannot detect things like 'does this commit correspond to a single logical change?' programmatically, there is a lot that can be detected, which this project does!


What it does

This tool provides a modular framework within which linters that check various things can be added. Out of the box, the following linters are currently provided:

  • Commit Message Pattern: Ensures that the commit message's title follows a maintainer-specified regular expression, and is under a certain character limit. Also enforces a character limit on each subsequent line of the commit message.
  • Imperative Form: Ensures that the commit message uses the imperative form, which is considered good practice.
  • Diff Size: Warns if a commit has a diff that is too large, which may be indicative of several logically unrelated changes being squashed into a single commit. image
  • Backwards Merge: Warns if a commit is a backward merge, that is, a merge from the upstream integration branch into the current topic-branch. The usual flow of commits is from topic to integration branches, hence this could be something to look into. image
  • Merge Commits: Warns if merge-commits exist in topic-branches. Usually, such commits appear only in upstream integration branches and thus may indicate a fishy history. merge-commit-linter
  • Repeated Commit Messages: It is easy to use command recall on your terminal and reuse the last commit message, but it makes the log look very ugly. Don't worry, this linter detects just that.

These linters are of two kinds, single-commit and multi-commit. Those of the first kind only analyze one commit from the history at a time, while those of the second look at and compare several of them at once. This provides flexibility in terms of what a linter can detect while maintaining a uniform and streamlined way or reporting those findings to the user.

Many of these linters are configurable, such as the regular expression used by the Commit Message Pattern linter, and these are specified for each repository using a configuration file. .git-lint-branch

How we built it

The project is built using Python. We use pygit2 for interfacing with the git objects, which are then processed by each linter. Natural language processing tasks are performed using spacy. For an elegant CLI we use typer and the beautiful colors are made possible using colorama.

What we learnt

We learnt a lot of git in the process. All of us use git every day, but what goes on behind the scenes inside the .git directory was something new. We also learned about maintaining clean git histories: we used git-lint-branch to keep things tidy while developing git-lint-branch!

What's next for git-lint-branch

We have several more linters in the oven, including ones that complain if source code is edited without the tests being accordingly modified and ones that detect commits that should perhaps be squashed but aren't. We also plan to make the program a lot more customizable, allowing the maintainers to specify which linters to run, and what the severity of them failing should be. This way, a big enough problem can cause CI to fail, letting everyone know something's wrong somewhere in those git logs!

Note: Screen images simulated based on the actual program output. Watch the video or try it out yourself to see the real thing in action.

Submission Category: Remote work/Tooling

Built With

  • colorama
  • pygit2
  • python
  • spacy
  • typer
Share this project: