Understanding `install` vs `install --install-hooks` about pre-commit.com HOT 7 CLOSED

Let me try and make a grid, but in list form of the possible commands / situations:

• pre-commit install
  • ✔️ installs .git/hooks/pre-commit
  • ✔️ keeps non-pre-commit hooks around (.git/hooks/pre-commit.legacy -- migration mode)
  • ❌ installs hook environments
  • ✔️ idempotent
• pre-commit install-hooks
  • ❌ installs .git/hooks/pre-commit
  • ❌ keeps non-pre-commit hooks around (.git/hooks/pre-commit.legacy -- migration mode)
  • ✔️ installs hook environments
  • ✔️ idempotent
• pre-commit install --install-hooks
  • ✔️ installs .git/hooks/pre-commit
  • ✔️ keeps non-pre-commit hooks around (.git/hooks/pre-commit.legacy -- migration mode)
  • ✔️ installs hook environments
  • ✔️ idempotent
• pre-commit install --install-hooks --force
  • ✔️ installs .git/hooks/pre-commit
  • ❌ keeps non-pre-commit hooks around (.git/hooks/pre-commit.legacy -- migration mode)
  • ✔️ installs hook environments
  • ✔️ idempotent

Basically, the only time you'd care about --install-hooks is if you want to eagerly install the hook environments before running -- it won't really make a difference but can help improve the perception that "pre-commit is slow" by frontloading the one-time install.

--force isn't really a necessary option unless you were previously using some other git hooks framework and want to no longer use that framework. ~technically all of the operations are idempotent but in the case of --force it's called out explicitly (similar to the way that rm -f and mkdir -p are idempotent)

The reason the full command is shown is that was the most common invocation at yelp where they were migrating from a 2k line bash-based git hooks framework and wanted make minimal to eagerly install the hook environments

from pre-commit.com.

The bit that always confuses me about this is I think of .git/hooks/pre-commit as a hook so my mind assumes install-hooks is creating that. It all makes sense once you realize hooks here means the venvs for the linters etc.

I get how it's rooted in the origins of pre-commit and it's probably too late to change. But calling the things it runs tools instead of hooks might've made some things clearer.

from pre-commit.com.

I don't think it's necessary at all, each of the options are independent and already documented -- if there's clarification needed for the individual options I'd suggest augmenting those

from pre-commit.com.

Thank you! That's very clear and helpful.

If it would help integrate that into the docs, I could built out a markdown table or such, or just send a PR if you would accept it.

from pre-commit.com.

Where do the hook environments get installed?

from pre-commit.com.

that's implementation detail -- but ${PRE_COMMIT_HOME:-${XDG_CACHE_HOME:-~/.cache}/pre-commit}/...

from pre-commit.com.

Cool, thanks. Yeah, don't intend to document this explicitly, just testing some behavior to make sure I get a couple things right.

from pre-commit.com.