From 33cce2b5ac9d6528815e266ad301e740374f54b5 Mon Sep 17 00:00:00 2001
From: Paolo Tranquilli <redsun82@github.com>
Date: Tue, 22 Feb 2022 15:42:16 +0100
Subject: [PATCH] add pre-commit configuration

This enables use of the `pre-commit` framework to run quick pre-commit
checks. In particular this allows to automatically fix:
* trailing white spaces
* absence or multiple newlines at the end of files
* QL code formatting
* file sync

More could be added in the future: anything that can be checked fast
can be added in the configuration (for example well-formedness of
`qldoc` files).

This is a purely opt-in feature. Instructions for enabling it and
possibly configuring its behaviour are in `pre-commit-hook-setup.md`.
---
 .pre-commit-config.yaml       | 21 +++++++++++++++++++++
 CONTRIBUTING.md               |  8 ++++++--
 docs/pre-commit-hook-setup.md | 18 ++++++++++++++++++
 3 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 .pre-commit-config.yaml

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 00000000000..c95ccf5f280
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,21 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+exclude: /test/.*$(?<!\.ql)(?<!\.qll)(?<!\.qlref)
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.2.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+-   repo: local
+    hooks:
+    -   id: codeql-format
+        name: Fix QL file formatting
+        files: \.qll?$
+        language: system
+        entry: codeql query format --in-place
+    -   id: sync-files
+        name: Fix files required to be identical
+        language: system
+        entry: python3 config/sync-files.py --latest
+        pass_filenames: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ae8ab1f4ac7..25bc584c3de 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,7 +42,11 @@ If you have an idea for a query that you would like to share with other CodeQL u
 
     - The queries and libraries must be autoformatted, for example using the "Format Document" command in [CodeQL for Visual Studio Code](https://help.semmle.com/codeql/codeql-for-vscode/procedures/about-codeql-for-vscode.html).
 
-    If you prefer, you can use this [pre-commit hook](misc/scripts/pre-commit) that automatically checks whether your files are correctly formatted. See the [pre-commit hook installation guide](docs/pre-commit-hook-setup.md) for instructions on how to install the hook.
+    If you prefer, you can either:
+    1. install the [pre-commit framework](https://pre-commit.com/) and install the configured hooks on this repo via `pre-commit install`, or
+    2. use this [pre-commit hook](misc/scripts/pre-commit) that automatically checks whether your files are correctly formatted.
+
+    See the [pre-commit hook installation guide](docs/pre-commit-hook-setup.md) for instructions on the two approaches.
 
 4. **Compilation**
 
@@ -63,6 +67,6 @@ After the experimental query is merged, we welcome pull requests to improve it.
 
 ## Using your personal data
 
-If you contribute to this project, we will record your name and email address (as provided by you with your contributions) as part of the code repositories, which are public. We might also use this information to contact you in relation to your contributions, as well as in the normal course of software development. We also store records of CLA agreements signed in the past, but no longer require contributors to sign a CLA. Under GDPR legislation, we do this on the basis of our legitimate interest in creating the CodeQL product. 
+If you contribute to this project, we will record your name and email address (as provided by you with your contributions) as part of the code repositories, which are public. We might also use this information to contact you in relation to your contributions, as well as in the normal course of software development. We also store records of CLA agreements signed in the past, but no longer require contributors to sign a CLA. Under GDPR legislation, we do this on the basis of our legitimate interest in creating the CodeQL product.
 
 Please do get in touch (privacy@github.com) if you have any questions about this or our data protection policies.
diff --git a/docs/pre-commit-hook-setup.md b/docs/pre-commit-hook-setup.md
index 9927acba85c..90420cb0bd1 100644
--- a/docs/pre-commit-hook-setup.md
+++ b/docs/pre-commit-hook-setup.md
@@ -14,3 +14,21 @@ ql/cpp/ql/src/printAst.ql would change by autoformatting.
 ```
 
 If you prefer to have the script automatically format the code (and not abort the commit), you can replace the line `codeql query format --check-only` with `codeql query format --in-place` (and `exit $exitVal` with `exit 0`).
+
+## Using the `pre-commit` framework
+
+Alternatively, you can use the [pre-commit framework](https://pre-commit.com/). There are some pre-commit hooks already configured on [`.pre-commit-config.yaml`](../.pre-commit-config.yaml). In order to install them you need to follow pre-commit's [installation instructions](https://pre-commit.com/#installation) and then run `pre-commit install`.
+
+By default, pre-commit will check and fix
+* trailing whitespaces;
+* absence of double newlines at end of files;
+* QL formatting;
+* files out of sync (see [`config/sync-files.py`](../config/sync-files.py)).
+
+It will run the checks only on files changed by the commit (except for the file sync check) and it will skip all files under `test` directories unless they are `.ql`, `.qll` or `.qlref` files.
+
+If you want to change one of these default behaviours (for example, you want to skip the out-of-sync file check, or you prefer to pass `--check-only` instead of `--in-place` to the query formatter), run
+```
+git update-index --assume-unchanged .pre-commit-config.yaml
+```
+and you can then modify the configuration at your will.