gitlint
gitlint copied to clipboard
jorisroovers
Document when one would want to use --staged
I was wondering why I'd need to set user.name and user.email when running gitlint with pre-commit in CI, and realized it's because of --staged in the hook's default config. It wasn't immediately clear to me why I'd want --staged (turns out I don't), so I thought I'd document it.
Might be nice to also document that with --staged one needs those git configs set, but don't know if that's too much detail on this level.
Thanks for the suggestion. I can see that --staged maybe isn't the most prescriptive CLI flag.
I do think the sentence "Useful if checking other properties of a commit besides just the message." doesn't necessarily tell much more than the existing "Read staged commit meta-info from the local repository". I guess the word "meta-info" is where you got caught up?
Maybe we should change it to:
"Read staged commit meta-info (username, email, changed files, etc) from the local repository".
That would also keep the --help output concise. We can then still add more text to the docs to explain it better.
To me the interesting thing is why would I want to have staged commit meta-info read from the repo. In that sense, "if checking other properties of a commit besides just the message" is to the point and helpful to me.
On the other hand, the "(username, email, changed files, etc)" addition does add some detail, but leaves the question kind of open -- without having a look under the hood, I wouldn't know if gitlint needed that info for something not directly related to which properties of a commit I want to lint, or if I can leave it out.
But yeah, my suggestion isn't as concise as I'd like it to be, and it feels kind of silly to repeat it everywhere. The reason I added it to both --help and the config docs is that I could not decide which would be the place I'd look first for more info on the option. If I'd look at --help, it clearly would need to be there, and if I'd look at the web docs, I'd probably notice the same thing in the main page and I'm not sure if I'd search for more info elsewhere.
Added a more lengthy explanation in the docs and updated the --help output to something I believe is more descriptive. Thanks for bringing this up :)