From 689f1203f7b13fe80379b8859cfc8496c7332795 Mon Sep 17 00:00:00 2001
From: helly25 <marcus.borger@snyk.io>
Date: Thu, 25 Apr 2024 09:10:44 +0000
Subject: [PATCH] When `run` is called with `-v`, then show `hook.description`
 if available.

When developers run the pre-commit, they don't always understand what to or where to find more information. The hook description field is already present and often used to provide more descriptive information. For brevity this is not shown in normal cases, but this PR changes the tool behavior to show the description in verbose mode (`-v`). So most users won't see any difference but this can easily be enabled for people who want it.

Alternatives considered:
* Always show the description: Some people may not like this though as it can be spammy.
* Provide a new field: Possible but seems to be just more work with description already present and not otherwise used.
* Show the `repo` link. This is at the wrong level and has a slightly different purpose. Though description can just be set to the same url where that is correct.
---
 .gitignore                                    |  2 ++
 pre_commit/commands/run.py                    |  7 +++++++
 .../failing_hook_repo/.pre-commit-hooks.yaml  |  3 +++
 tests/commands/run_test.py                    | 20 +++++++++++++++++++
 4 files changed, 32 insertions(+)

diff --git a/.gitignore b/.gitignore
index c2021816..78c61ff1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,8 @@
 *.egg-info
 *.py[co]
+*.pytest_cache
 /.coverage
 /.tox
+/build
 /dist
 .vscode/
diff --git a/pre_commit/commands/run.py b/pre_commit/commands/run.py
index 2a08dff0..44a7aa4c 100644
--- a/pre_commit/commands/run.py
+++ b/pre_commit/commands/run.py
@@ -222,6 +222,13 @@ def _run_single_hook(
 
         if retcode:
             _subtle_line(f'- exit code: {retcode}', use_color)
+            if verbose and hook.description:
+                if '\n' in hook.description:
+                    _subtle_line('- description: |', use_color)
+                    for l in hook.description.splitlines():
+                        _subtle_line('  ' + l, use_color)
+                else:
+                    _subtle_line(f'- description: {hook.description}', use_color)
 
         # Print a message if failing due to file modifications
         if files_modified:
diff --git a/testing/resources/failing_hook_repo/.pre-commit-hooks.yaml b/testing/resources/failing_hook_repo/.pre-commit-hooks.yaml
index 118cc8b1..e74f7b48 100644
--- a/testing/resources/failing_hook_repo/.pre-commit-hooks.yaml
+++ b/testing/resources/failing_hook_repo/.pre-commit-hooks.yaml
@@ -1,5 +1,8 @@
 -   id: failing_hook
     name: Failing hook
+    description: |
+        Failing Hook Description
+        Longer description.
     entry: bin/hook.sh
     language: script
     files: .
diff --git a/tests/commands/run_test.py b/tests/commands/run_test.py
index 50a20f37..bbf9773c 100644
--- a/tests/commands/run_test.py
+++ b/tests/commands/run_test.py
@@ -173,6 +173,26 @@ def test_run_all_hooks_failing(cap_out, store, repo_with_failing_hook):
     )
 
 
+def test_run_all_hooks_failing_verbose(cap_out, store, repo_with_failing_hook):
+    _test_run(
+        cap_out,
+        store,
+        repo_with_failing_hook,
+        {'verbose': True},
+        (
+            b'Failing hook',
+            b'Failed',
+            b'hook id: failing_hook',
+            b'description: |',
+            b'  Failing Hook Description',
+            b'  Longer description.',
+            b'Fail\nfoo.py\n',
+        ),
+        expected_ret=1,
+        stage=True,
+    )
+
+
 def test_arbitrary_bytes_hook(cap_out, store, tempdir_factory):
     git_path = make_consuming_repo(tempdir_factory, 'arbitrary_bytes_repo')
     with cwd(git_path):