Document pre-commit hook for staged files

[alyssaruth]

Relates to: #1057, #1792, #2175, #2320, #3078

I just got finished implementing a "partial" detekt hook for my team, so I'm raising a PR to document it since it has been asked about many times in the past. Our use case is that we want a hook for "fast feedback" (i.e. not having to wait for a CI build to find out you've violated a check) - as such, we want it to run quickly and aren't too fussed if it occasionally misses things (because CI will still pick those cases up for us, by running a full check).

I've included a disclaimer that checks requiring types won't work properly, however I am yet to verify exactly what will happen in this scenario. Are the affected checks simply skipped when using the --include flag? That's what I'm hoping is the case... it would be more problematic if they fall over or might produce false positives etc!

Anyhow, hopefully this can be of use to someone. Thanks for developing and maintaining this tool! 😄

[codecov]

Codecov Report

Merging #4711 (e4f6b07) into main (966cc50) will increase coverage by 84.71%.
The diff coverage is n/a.

❗ Current head e4f6b07 differs from pull request most recent head dd61829. Consider uploading reports for the commit dd61829 to get more accurate results

@@             Coverage Diff             @@
##             main    #4711       +/-   ##
===========================================
+ Coverage        0   84.71%   +84.71%     
- Complexity      0     3423     +3423     
===========================================
  Files           0      490      +490     
  Lines           0    11255    +11255     
  Branches        0     2069     +2069     
===========================================
+ Hits            0     9535     +9535     
- Misses          0      675      +675     
- Partials        0     1045     +1045     

Impacted Files	Coverage Δ
...ch/detekt/rules/style/ExplicitItLambdaParameter.kt	100.00% <0.00%> (ø)
.../formatting/wrappers/SpacingAroundRangeOperator.kt	100.00% <0.00%> (ø)
.../kotlin/io/gitlab/arturbosch/detekt/cli/CliArgs.kt	100.00% <0.00%> (ø)
...ab/arturbosch/detekt/core/config/ValidateConfig.kt	100.00% <0.00%> (ø)
...ch/detekt/formatting/wrappers/MaximumLineLength.kt	100.00% <0.00%> (ø)
...lab/arturbosch/detekt/api/internal/PathMatchers.kt	100.00% <0.00%> (ø)
...ekt/formatting/wrappers/NoConsecutiveBlankLines.kt	100.00% <0.00%> (ø)
...kt/rules/style/LibraryEntitiesShouldNotBePublic.kt	88.46% <0.00%> (ø)
...b/arturbosch/detekt/core/config/CompositeConfig.kt	75.00% <0.00%> (ø)
...t/generator/collection/RuleSetProviderCollector.kt	78.04% <0.00%> (ø)
... and 480 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 966cc50...dd61829. Read the comment docs.

[cortinico]

Nice addition 👍

[cortinico]

I would link to the Using Type Resolution page here rather than a specific rule

[BraisGabin]

Thanks! The main problem of mixing cli and gradle is the baseline, I think. If you don't use it, all is fine, but when you run the cli, usually you run it just once for all the project but the baseline is usually per-project/module. And if you uses type solving you enve have two baselines: main and test. And hopefully you don't have multiple build variants on Android... It's a mess.

But I agree that this fast loop is good so we can add it and iterate it later. This baseline-mess should be something to fix for 2.0

[alyssaruth]

Thanks! The main problem of mixing cli and gradle is the baseline, I think. If you don't use it, all is fine, but when you run the cli, usually you run it just once for all the project but the baseline is usually per-project/module. And if you uses type solving you enve have two baselines: main and test. And hopefully you don't have multiple build variants on Android... It's a mess.

But I agree that this fast loop is good so we can add it and iterate it later. This baseline-mess should be something to fix for 2.0

Happily we're not using the baseline stuff, so I haven't encountered these problems. There is a more minor issue with mixing gradle and CLI, though - I have to pipe a few arguments in our hook so the CLI properly mimics our gradle config (--build-upon-default-config --config '/foo/bar.yml'). So we're kinda maintaining that in two places - I'll have to update our hook in-step with the gradle side to avoid unexpected behaviour. But I'm not anticipating that to change often now it's set up for our project 🤞

Another option would be to try and get the file list to ./gradlew detekt-cli somehow, but that seemed harder and would have had the daemon warm-up problem 🤷

[schalkms]

I like having a more comprehensive documentation regarding commit hooks. Thank you very much!

[alyssaruth]

We ran into an issue using the hook so I've just pushed our updated version - the detekt CLI produces no output if it's successful (as opposed to the ./gradlew process, which will at least output some gradle bits). This meant the rm $OUTPUT final line failed, because no file was created.

I've simplified it to not use a file at all 😄