Working with pre-commit

[wenzowski]

@BryanGK any notes/tips from our call on pre-commit that can be recorded in the repo docs? Maybe a bit about the 3 versions of every file that make up our git authoring lifecycle (HEAD, Staged, Unstaged), a bit about running hooks directly from the .git folder, thoughts on how to respond to failed pre-commit hooks, and/or something about when/where to write commit messages so they don't get blown away by a failed pre-commit hook?

[BryanGK]

I'll create a pre-commit.md in the docs folder and let me see what I put together.

[BryanGK]

@wenzowski I'm putting together the docs for this issue but I can't quite remember what you said re: the git authoring lifecycle. It was something like pre-commit won't run on unstage files, is that correct? Is there anything else to add? Would you happen to have some docs I can read about it?

I'll push up what I have so far and link back to this issue, if you wouldn't mind giving me some ideas of how I can make it better would be much appreciated.

[wenzowski]

Running hooks on unstaged changes can lead to both false-positives and false-negatives during committing. pre-commit only runs on the staged contents of files by temporarily saving the contents of your files at commit time and stashing the unstaged changes while running hooks.
https://pre-commit.com/#pre-commit-during-commits

pre-commit itself will never touch the staging area. These are good ways to silently break commits. In my mind this is one of the worst things that lint-staged does and suggests -- hooks are very frequently not perfect and magically changing what's being committed should not be taken lightly.
pre-commit/pre-commit#747 (comment)

So when working with pre-commit we need to always have staged all the changes we intend to commit, and if a hook that changes our code fails we need to go through and manually stage the changes made by pre-commit, preferably reviewing them as we go with, say, git add -p otherwise we won't be able to commit.