From 858c8dfc2a982dc7ee8db6314212502db63b91f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20de=20Sousa?= Date: Sat, 1 Jul 2023 15:19:44 +0200 Subject: [PATCH] contributing: Expand instructions on pre-commit (#3006) * contributing: Expands instructions on Pre-commit * contributing: Corrects character case in various nouns * Update doc/development/submitting/submitting.md Co-authored-by: Veronica Andreo * Update doc/development/submitting/submitting.md Co-authored-by: Veronica Andreo --------- Co-authored-by: Veronica Andreo --- doc/development/submitting/submitting.md | 38 +++++++++++++++++++----- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/doc/development/submitting/submitting.md b/doc/development/submitting/submitting.md index 5fa676b0eac..fb1a60af10b 100644 --- a/doc/development/submitting/submitting.md +++ b/doc/development/submitting/submitting.md @@ -21,39 +21,61 @@ Be sure to check your code against these rules: ### Use pre-commit -It is highly recommended to install and use [Pre-commit](https://pre-commit.com) -before submitting any new or modification of code or other content. The Pre-commit -git hooks set are checking validity and executes formatting of file formats for -a range of files types, including C/C++ and Python files. Pre-commit installs +It is highly recommended to install and use [pre-commit](https://pre-commit.com) +before submitting any new or modified code or any other content. The pre-commit +Git hooks set checks validity and executes automated formatting for +a range of file formats, including C/C++ and Python. Pre-commit installs all necessary tools in a virtual environment upon first use. +If you never used pre-commit before, you must start by installing it on your +system. You only do it once: + ```bash python -m pip install pre-commit +``` + +Pre-commit must then be activated in the code repository. Change the directory +to the root folder and use the `install` command: +```bash cd # once per repo pre-commit install ``` -Pre-commit will then be automatically triggered by git commit command. It is -also possible to run manually, e.g: +Pre-commit will then be automatically triggered by the `git commit` command. If +it finds any problem it will abort the commit and try to solve it automatically. +In that case review the changes and run again `git add` and +`git commit`. + +It is also possible to run pre-commit manually, e.g: ```bash pre-commit run clang-format --all-files pre-commit run black --all-files ``` -The Pre-commit hooks are defined in +Or to target a specific set of files: + +```bash +pre-commit run --files raster/r.somemodule/* +``` + +The pre-commit hooks set is defined in [.pre-commit-config.yaml](../../../.pre-commit-config.yaml). -It is possible to temporary disable the Pre-commit hooks in the repo, eg. while +It is possible to temporally disable the pre-commit hooks in the repo, e.g. while working on older branches: ```bash # backporting... pre-commit uninstall +``` + +And to reactivate pre-commit again: +```bash git switch main pre-commit install ```