Add --commit flag to more easily lint a single commit

[WGH-]

The documentation suggests to use the following syntax for linting a single commit:

# Or specify a single specific commit in refspec format, like so:
gitlint --commits "019cf40^...019cf40"

https://jorisroovers.com/gitlint/#linting-a-range-of-commits

However, this syntax doesn't work for the initial commit, because it has no parent.

$ git log
commit 5bb07b5f891178c29bee44d0b18bc826d3e4b177
Author: WGH <wgh@torlan.ru>
Date:   Wed Aug 12 13:58:14 2020 +0300

    Initial commit
$ gitlint --commits 5bb07b5f891178c29bee44d0b18bc826d3e4b177^...5bb07b5f891178c29bee44d0b18bc826d3e4b177
An error occurred while executing '/usr/bin/git rev-list 5bb07b5f891178c29bee44d0b18bc826d3e4b177^...5bb07b5f891178c29bee44d0b18bc826d3e4b177': b"fatal: ambiguous argument '5bb07b5f891178c29bee44d0b18bc826d3e4b177^...5bb07b5f891178c29bee44d0b18bc826d3e4b177': unknown revision or path not in the working tree.\nUse '--' to separate paths from revisions, like this:\n'git <command> [<revision>...] -- [<file>...]'"

[jorisroovers]

Hi! Thanks for opening the issue.

I agree this doesn't work, but this is correct behavior. Note the following line right below where you copied that example from:

The --commits flag takes a single refspec argument or commit range. Basically, any range that is understood by git rev-list as a single argument will work.

In other words, gitlint just passes the refspec onto git itself. Turns out, your example isn't valid refspec. The good news is it's easy to fix by just changing your --commits argument.

Taking SHA 765a4427f80ccdda61bc78e2680bda14787b2a4e as an example (=gitlint's first commit, you get it via git rev-list --max-parents=0 HEAD).

# This doesn't work, because it's invalid refspec (as per git's definition)
$ git rev-list "765a4427f80ccdda61bc78e2680bda14787b2a4e^..765a4427f80ccdda61bc78e2680bda14787b2a4e" 
fatal: ambiguous argument '765a4427f80ccdda61bc78e2680bda14787b2a4e^..765a4427f80ccdda61bc78e2680bda14787b2a4e': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

# This *does* work!
$ git rev-list 765a4427f80ccdda61bc78e2680bda14787b2a4e
765a4427f80ccdda61bc78e2680bda14787b2a4e

# In other words, to lint the first commit you can just pass the SHA on its own
$ gitlint --commits 765a4427f80ccdda61bc78e2680bda14787b2a4e
3: B6 Body message is missing

Refspec is tricky and not always intuitive. I can see that the example from gitlint's docs doesn't consider this special first-commit case and might lead to some frustration as you experienced. I'll keep this issue open to update the docs accordingly!

[WGH-]

git rev-list $COMMIT_HASH will return all parents, if they exist. Which means if you want to lint a single commit, you will have to use different syntax depending on whether the commit has parents or not, which is somewhat annoying.

[jorisroovers]

You're right.

Unfortunately, it comes down to how refspec works. I originally wanted to support using a single commit SHA to specify a single commit to lint, but that goes directly against the refspec format where a single SHA usually defines a range of commits.

I spend a lot of time pondering about this and ultimately decided it's best to not change semantics and pass the refspec directly to git. I'm not against revisiting that, but I do have a pretty strong opinion against gitlint having an internal refspec parser. That is both tricky to get right (example: #23, #35) and arguably poor practice (we should avoid re-implement core git features).

So it's a trade-off - I don't think there's a perfect solution. Hope that makes sense :-)

Again, I'll clarify this in the docs!

[WGH-]

What do you think about a new option that would accept a single commit, and nothing else?

[jorisroovers]

Yes, possible 👍

I'll leave this here 😎
https://jorisroovers.com/gitlint/contributing/

(Most of the work is in writing tests/docs, not the business logic itself).