Make installation opt-out

... with a possiblity to opt back in on a per project basis by
running the script.

Author: roberth

README.md

@@ -72,6 +72,15 @@ https://devenv.sh/pre-commit-hooks/
      references the binaries, for speed and safe garbage collection
    - provide the `pre-commit` executable that `git commit` will invoke
 
+## Opting out, opting in
+
+Users can enforce their own preference by setting `NIX_PRE_COMMIT_HOOKS_INSTALL` to `0` or `1` in their environment, e.g. in `.profile` or in [`home.sessionVariables`](https://nix-community.github.io/home-manager/options.html#opt-home.sessionVariables) for home-manager users.
+
+Furthermore, project maintainers can set a default preference via the `installByDefault` option.
+
+Finally, regardless of these settings, you may install the hooks manually by running `nix-pre-commit-hooks-install` in your shell. This does what it says, and the shell hook will detect that the hooks exist and keep them up to date.
+
+
 ## Optional
 
 ### Direnv

modules/pre-commit.nix

@@ -291,6 +291,29 @@ in
           readOnly = true;
         };
 
+      installByDefault =
+        mkOption {
+          type = types.bool;
+          default = true;
+          description = lib.mdDoc ''
+            Whether to install the hooks _by default_.
+
+            By priority, the behavior of `installationScript` (ie `nix develop`)
+            is controlled by the user's `NIX_PRE_COMMIT_HOOKS_INSTALL` environment
+            variable. The purpose of this variable is that users can globally override
+            the use of `pre-commit` for all their projects.
+
+            Regardless of any settings, you can still install the hooks by running:
+
+            ```bash
+            nix-pre-commit-hooks-install
+            ```
+
+            After running that, the pre-commit hooks scripts and config file will be
+            updated by `installationScript` (ie `nix develop`) as usual.
+          '';
+        };
+
       src =
         lib.mkOption {
           description = lib.mdDoc ''
@@ -375,6 +398,8 @@ in
       installationScript = ''
         export PATH=${cfg.package}/bin:$PATH
 
+        export NIX_PRE_COMMIT_HOOKS_INSTALL="''${NIX_PRE_COMMIT_HOOKS_INSTALL:-${if cfg.installByDefault then "1" else "0"}}"
+
         nix-pre-commit-hooks-update() {
           local git_dir
           if ! type -t git >/dev/null; then
@@ -389,7 +414,7 @@ in
 
             if readlink .pre-commit-config.yaml >/dev/null \
               && [[ $(readlink .pre-commit-config.yaml) == ${configFile} ]]; then
-              echo 1>&2 "pre-commit-hooks.nix: hooks up to date"
+              echo 1>&2 "pre-commit-hooks.nix: hooks config is up to date"
             else
               echo 1>&2 "pre-commit-hooks.nix: updating $PWD repo"
 
@@ -405,9 +430,17 @@ in
                 ln -s ${configFile} .pre-commit-config.yaml
                 # Remove any previously installed hooks (since pre-commit itself has no convergent design)
                 hooks="pre-commit pre-merge-commit pre-push prepare-commit-msg commit-msg post-checkout post-commit"
-                for hook in $hooks; do
-                  pre-commit uninstall -t $hook
-                done
+
+                # ... but if the user has opted out of automatic installation,
+                # don't uninstall, because in that case already-installed hooks
+                # represent a deliberate choice, and we don't want to keep them
+                # and maintain them.
+                if [[ "$NIX_PRE_COMMIT_HOOKS_INSTALL" == 1 ]]; then
+                  for hook in $hooks; do
+                    pre-commit uninstall -t $hook
+                  done
+                fi
+
                 # Add hooks for configured stages (only) ...
                 if [ ! -z "${concatStringsSep " " install_stages}" ]; then
                   for stage in ${concatStringsSep " " install_stages}; do
@@ -426,17 +459,35 @@ in
                         exit 1
                         ;;
                     esac
-                    pre-commit install -t $stage
+                    # If the user environment doesn't want hooks, don't install them
+                    # If the hook already exists, update the embedded pre-commit package version,
+                    # because they may have opted in by running `nix-pre-commit-hooks-install`
+                    if [[ "$NIX_PRE_COMMIT_HOOKS_INSTALL" == 1 ]] || \
+                       [[ -e "$gitdir/hooks/$stage" ]]; then
+                      pre-commit install -t $stage
+                    fi
                   done
                 # ... or default 'pre-commit' hook
                 else
-                  pre-commit install
+                  if [[ "$NIX_PRE_COMMIT_HOOKS_INSTALL" == 1 ]] || \
+                      [[ -e "$gitdir/hooks/pre-commit" ]]; then
+                    pre-commit install
+                  else
+                    echo 1>&2 "pre-commit-hooks.nix: skipping installation of pre-commit hook scripts. Run 'nix-pre-commit-hooks-install' to install them."
+                  fi
                 fi
               fi
             fi
           fi
         }
 
+        nix-pre-commit-hooks-install() {
+          # Make sure installation will run
+          [ -L .pre-commit-config.yaml ] && unlink .pre-commit-config.yaml
+
+          NIX_PRE_COMMIT_HOOKS_INSTALL=1 nix-pre-commit-hooks-update
+        }
+
         nix-pre-commit-hooks-update
       '';
     };