diff --git a/INSTALL.md b/INSTALL.md index 34bf5dbc4..5a78aa14b 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -128,7 +128,7 @@ The `./scripts/control_stack.sh` script will automatically create directories an ## Installing Python and Path Verification -As noted in the [dependencies](doc/DEPENDENCIES.md), Python, the Python development package, and Pip should be installed in the appropriate manner for your environment. +As noted in the [dependencies](doc/DEPENDENCIES.md), Python, the Python development package, Pip, and pre-commit should be installed in the appropriate manner for your environment. ### Different Python Executable Names It is quite common for the Python executables to be named `python3`, `python311`, `pip3`, etc. in the *global* Python environment, instead of just `python` and `pip`. This is accounted for when [creating a virtual environment](#using-a-virtual-environment), provided the right Python command was used to create it. Users not doing this should consider setting up shell aliases, symlinks in their path, or some other mechanism to ensure `python` and `pip` execute the desired versions appropriately. diff --git a/doc/DEPENDENCIES.md b/doc/DEPENDENCIES.md index e35a8c398..525f12947 100644 --- a/doc/DEPENDENCIES.md +++ b/doc/DEPENDENCIES.md @@ -25,6 +25,7 @@ The DMOD project has two related sets of dependencies: | Python Development Headers/Libs | Analogous to installed Python version | Required for building certain Python dependency wheels; e.g., *pandas* | | C++ Compiler | | Required for building certain Python dependency wheels; e.g., *pandas* | | Python Packages | See [requirements.txt](../requirements.txt) | Recommend installing in Python virtual environment | +| pre-commit | See [.pre-commit-config.yaml](../.pre-commit-config.yaml) | Recommend installing in Python virtual environment | ## Dependency Caveats The strictness of these dependencies can vary in different situations, in a way that is hard to define concisely. E.g., one could probably avoid installing Bash by manually performing all the tasks handled by Bash scripts [^1]. Also, OpenSSL is not needed (locally) if all required SSL certificates can be provided from elsewhere. And somewhat related: multi-node deployments probably don't need ***all*** dependencies on the non-primary node(s). diff --git a/gitflow.md b/gitflow.md index af52fe4ec..24502a1db 100644 --- a/gitflow.md +++ b/gitflow.md @@ -39,6 +39,31 @@ OR Development work should commit frequently when changes are complete and meaningful. If work requires modifying more than one file in the source, it is recommended to commit the changes independently to help avoid too large of conflicts if the occur. +### Setting up `pre-commit` hooks + +[`pre-commit`](https://pre-commit.com/) is used to manage and install `git` pre-commit hooks. +pre-commit hooks run automatically when `git commit` is invoked and perform checks on the code you are committing. +Example checks are removing trailing white spaces, verifying that large files are not included, or running a code linting tool. +Hooks are configured in the [`.pre-commit-config.yaml`](./.pre-commit-config.yaml) file in the root of the repo. + +`pre-commit` can be installed using a package manager (e.g. `brew install pre-commit`) or from `pip`. +If you are to use `pip`, it is highly recommend to use a virtual environment. + +Install pre-commit hooks into your `git` clone by running: + +```shell +pre-commit install +``` + +Hooks will now run when code is committed. +Alternatively, you can run the pre-commit hooks manually via: + +```shell +pre-commit run --all-files +``` + +For more information, see [`pre-commit`'s documentation](https://pre-commit.com/index.html). + ### Commits When changes are made to a file and ready for committing, then use these git commands