[CI] Update and document the pre-commit hooks (#2411)

Author: jbampton

.pre-commit-config.yaml

@@ -22,20 +22,23 @@ default_language_version:
   # force all unspecified Python hooks to run python3
   python: python3
   # force all unspecified Node hooks to run Node.js v22.17.0 LTS
-  node: 22.17.0
+  node: 22.20.0
 minimum_pre_commit_version: '3.2.0'
 repos:
   - repo: meta
     hooks:
       - id: identity
         name: run identity check
+        description: check you have set your git identity
       - id: check-hooks-apply
         name: run check hooks apply
+        description: check that all the hooks apply to the repository
   - repo: https://github.com/thlorenz/doctoc.git
     rev: v2.2.0
     hooks:
       - id: doctoc
-        name: Add TOC for Markdown and RST files
+        name: add TOC for Markdown files
+        description: automatically keeps your table of contents up to date
         files: ^README\.md$
   - repo: local
     hooks:
@@ -69,6 +72,7 @@ repos:
         files: (?i)\.zip$
       - id: check-makefiles-tabs
         name: check Makefiles files for tabs
+        description: ensures that Makefiles are indented with tabs
         entry: ./scripts/pre-commit/check_makefiles_for_tabs.sh # Path to your script
         language: system
         files: '(?i)makefile$'
@@ -80,11 +84,13 @@ repos:
     hooks:
       - id: chmod
         name: set file permissions
+        description: manual hook to be run by macOS or Linux users for a full repository clean up
         args: ['644']
         files: \.md$
         stages: [manual]
       - id: insert-license
         name: add license for all .c files
+        description: automatically adds a licence header to all C files that don't have a license header
         files: \.c$
         args:
           - --comment-style
@@ -94,6 +100,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all .h files
+        description: automatically adds a licence header to all header files that don't have a license header
         files: \.h$
         args:
           - --comment-style
@@ -103,6 +110,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all Java files
+        description: automatically adds a licence header to all Java files that don't have a license header
         files: \.java$
         args:
           - --comment-style
@@ -112,6 +120,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all Markdown files
+        description: automatically adds a licence header to all Markdown files that don't have a license header
         files: \.md$
         args:
           - --comment-style
@@ -122,6 +131,7 @@ repos:
         exclude: ^docs/index\.md$|^\.github/pull_request_template\.md$|\.github/issue_template\.md$|^docs/blog/.*\.md$
       - id: insert-license
         name: add license for all Makefile files
+        description: automatically adds a licence header to all Makefiles that don't have a license header
         files: ^Makefile$
         args:
           - --comment-style
@@ -131,6 +141,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all R files
+        description: automatically adds a licence header to all R files that don't have a license header
         files: \.R$
         args:
           - --comment-style
@@ -140,6 +151,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all Scala files
+        description: automatically adds a licence header to all Scala files that don't have a license header
         files: \.scala$
         args:
           - --comment-style
@@ -149,6 +161,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all TOML files
+        description: automatically adds a licence header to all TOML files that don't have a license header
         files: \.toml$
         args:
           - --comment-style
@@ -158,6 +171,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all YAML files
+        description: automatically adds a licence header to all YAML files that don't have a license header
         files: \.ya?ml$
         args:
           - --comment-style
@@ -167,6 +181,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all Python files
+        description: automatically adds a licence header to all Python files that don't have a license header
         files: \.py$
         args:
           - --comment-style
@@ -176,6 +191,7 @@ repos:
           - --fuzzy-match-generates-todo
       - id: insert-license
         name: add license for all other files
+        description: automatically adds a licence header to all other files that don't have a license header
         files: ^\.(editorconfig|gitattributes|prettierignore|prettierrc|shellcheckrc)$|^.*/\.gitignore$
         args:
           - --comment-style
@@ -184,12 +200,14 @@ repos:
           - .github/workflows/license-templates/LICENSE.txt
           - --fuzzy-match-generates-todo
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.20.0
+    rev: v3.21.0
     hooks:
       - id: pyupgrade
+        name: run pyupgrade
+        description: a tool (and pre-commit hook) to automatically upgrade syntax for newer versions of the language
         args: [--py37-plus]
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 25.1.0
+    rev: 25.9.0
     hooks:
       - id: black-jupyter
         name: run black-jupyter
@@ -219,7 +237,7 @@ repos:
         args: [--ignore-words=.github/linters/codespell.txt]
         exclude: ^docs/image|^spark/common/src/test/resources|^docs/usecases|^tools/maven/scalafmt|osmpbf/build|^docker/zeppelin|^docs-overrides
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.27.2
+    rev: v8.28.0
     hooks:
       - id: gitleaks
         name: run gitleaks
@@ -234,7 +252,7 @@ repos:
       - id: rst-inline-touching-normal
         name: detect mistake of inline code touching normal text in rst
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: check-ast
         name: run check-ast
@@ -268,24 +286,50 @@ repos:
         name: run check-toml
         description: check TOML files for syntax errors
       - id: check-vcs-permalinks
+        name: run check-vcs-permalinks
+        description: ensures that links to vcs websites are permalinks
       - id: check-xml
+        name: run check-xml
+        description: attempts to load all xml files to verify syntax
       - id: check-yaml
+        name: run check-yaml
+        description: attempts to load all yaml files to verify syntax
         exclude: ^mkdocs\.yml$
       - id: debug-statements
+        name: run debug-statements
+        description: check for debugger imports and py37+ `breakpoint()` calls in python source.
       - id: destroyed-symlinks
+        name: run destroyed-symlinks
+        description: detects symlinks which are changed to regular files with a content of a path which that symlink was pointing to
       - id: detect-aws-credentials
+        name: run detect-aws-credentials
+        description: checks for the existence of AWS secrets that you have set up with the AWS CLI
         args: [--allow-missing-credentials]
       - id: detect-private-key
+        name: run detect-private-key
+        description: checks for the existence of private keys
       - id: end-of-file-fixer
+        name: run end-of-file-fixer
+        description: makes sure files end in a newline and only a newline
         exclude: \.svg$|^docs/image|^spark/common/src/test/resources
       - id: file-contents-sorter
+        name: run file-contents-sorter
+        description: sort the lines in specified files (defaults to alphabetical)
         args: [--unique]
         files: ^\.github/linters/codespell\.txt$
       - id: fix-byte-order-marker
+        name: run fix-byte-order-marker
+        description: removes UTF-8 byte order marker
       - id: forbid-submodules
+        name: run forbid-submodules
+        description: forbids any submodules in the repository
       - id: mixed-line-ending
+        name: run mixed-line-ending
+        description: replaces or checks mixed line ending
         exclude: \.csv$
       - id: name-tests-test
+        name: run name-tests-test
+        description: verifies that test files are named correctly
         args: [--pytest-test-first]
         exclude: |
           (?x)^(
@@ -298,8 +342,12 @@ repos:
               python/tests/tools\.py
           )$
       - id: requirements-txt-fixer
+        name: run requirements-txt-fixer
+        description: sorts entries in the Python requirements files and removes incorrect entry for pkg-resources==0.0.0
         files: ^docker/requirements\.txt$
       - id: trailing-whitespace
+        name: run trailing-whitespace
+        description: trims trailing whitespace
         args: [--markdown-linebreak-ext=md]
         exclude: ^docs-overrides/main\.html$|\.Rd$
   - repo: https://github.com/igorshubovych/markdownlint-cli
@@ -313,7 +361,7 @@ repos:
         types: [markdown]
         files: \.(md|mdown|markdown)$
   - repo: https://github.com/shellcheck-py/shellcheck-py
-    rev: v0.10.0.1
+    rev: v0.11.0.1
     hooks:
       - id: shellcheck
         name: run shellcheck
@@ -336,7 +384,9 @@ repos:
         args: ['--fix', '-o', '4', '--strip', 'safe', '--alpha']
         stages: [manual]
   - repo: https://github.com/adamchainz/blacken-docs
-    rev: 1.19.1
+    rev: 1.20.0
     hooks:
       - id: blacken-docs
+        name: run blacken-docs
+        description: run `black` on python code blocks in documentation files
         additional_dependencies: [black==25.1.0]