Skip to content

git precommit hooks

Jump to bottom
Martin Shetty edited this page Jun 21, 2022 · 1 revision

If you intend to check out and edit the repository locally, you should install pre-commit and activate it for this repository. We use pre-commit to autoformat code and documentation pages.

Windows only

If you are using Windows, there is some extra work. Otherwise, you can skip over this section.

You should check that both python and pip run in git bash. If not, make sure you have a recent version of python and pip installed and your path variable points to your python and python script directories.

  1. How to check if pip is installed?
    Type in the following command at the command prompt:
    pip help
    If pip help responds, then pip is installed. Otherwise, there will be an error saying the program could not be found.
    pip is automatically installed with Python 2.7.9+ and Python 3.4+.
  2. How to check if Python is installed?
    Type in the following command at the command prompt:
    python
    If this command is not unrecognized, you need to install Python before you can install pip.
    If the command is recognized, Python responds with its version and a list of commands.

If they are not installed, you can visit python.org to get the latest version of Python`, which will also install pip. Installing Python from the Windows app store may cause some issues with the 'Path' variable later. So, it is recommended that you install it from the website itself. Once you have downloaded the installer from the website, run it. In the first prompt, please check the box next to the 'Add Python version_number to PATH'.
If you have installed Python already beforehand, or if you forgot to check that box, you may have to add the path to the folders containing the .exe files for both Python and pip in the 'Path' system variable. To do this:

  1. Search 'system env' in your Start Menu.
  2. Click 'Environment Variables'
  3. Edit the 'Path' variable
  4. Add 2 new paths which might look something like this, depending on where you installed the programs 'C:\Users\username\AppData\Local\Programs\Python\Python39'
    'C:\Users\username\AppData\Local\Programs\Python\Python39\Scripts'
    These MUST contain the .exe files of python and pip respectively.
  5. Open Command Prompt again and type 'python' And you should get the interactive prompt with >>> showing that python is running.

There are some notes on this here, here and here.

You will also likely have to install Visual Studio, in particular, the "Desktop development with C++" package, otherwise the steps below may fail. You can download it here. You are now ready to install the pre-commit.

Installing pre-commit

On Debian/Ubuntu or Windows:

(sudo) pip install pre-commit

or (macOS):

brew install pre-commit

Then activate pre-commit in this repository, by running the following in the repository path:

pre-commit install

Now, every time you commit, this utility will check your changed files for formatting issues. If it reports any problems, it will also fix those files. So all you have to do is add and commit again.

Consequently, if you need to trigger pre-commit to check specific files, just edit those files by adding some whitespace, and make a commit.

If at any point you want to run pre-commit over all the changes in your branch (e.g. to reformat things), try

pre-commit run --from-ref $(git merge-base origin/master HEAD) --to-ref HEAD

If you fail to do this, automatic checks will fail and you will not be allowed to merge your changes.

Updating clang-format configuration

There should be a .clang-format file in the software directory. Alternative configurations can be set up in sub-directories to override it for those parts of the code. Take note that if you need to generate a new .clang-format file, this must be done with the same version of clang-format as used by pre-commit, not the one that may be installed natively on your system. If versions don't match, the checks may "fail" silently -- i.e. mistakenly think checks have passed.

The way to track down the correct executable is to follow the code here: https://github.com/RespiraWorks/pre-commit-hooks/blob/master/clang_format.py And find the commit sha for your operating system and see the download path string that gets generated further in this same source file. Then you can run something like:

/home/john/.cache/pre-commit-jlebar/clang-format-1baf0089e895c989a311b6a38ed94d0e8be4c0a7 --style=Google --dump-config > .clang-format

to generate the new config file.

Clone this wiki locally