mpyhooks

This tool provides various hooks to check file content in a repository, with many originating from the OpenFOAM Foundation’s code style guide. The hooks can be easily integrated with pre-commit for automated checking.

Usage

mpyhooks <hook> [options] [files ...]

Available Hooks

encoding - Preview File Encoding

Check encoding for Markdown preview files in Rodare (Rossendorf Data Repository).

Usage:

mpyhooks encoding file1 file2 ...

line-length - Line Length Check

Check for line length less than 80 characters. Enforces maximum line length following OpenFOAM Foundation software style guide.

Usage:

mpyhooks line-length file1.C file2.H ...

ifndef - Header Guard Check

Check for #ifndef directive and #define statements in header files. Ensures proper include guards in header files. The hook tries to detect regular header files and will skip header files that contain pure source code only. The detection is based on a test for #pragma once, #ifndef or #define.

Usage:

mpyhooks ifndef MyClass.H ...

Expected format:

#ifndef MyClass_H
#define MyClass_H

// ... content ...

#endif

tabs - Tab Replacement

Check for tabs in files and replaces them with spaces (default are 4).

Usage:

mpyhooks tabs file1.C file2.py ...

non-standard-code - Code Style Check

Checks for non-standard C++ patterns per OpenFOAM Foundation software guidelines.

Usage:

mpyhooks non-standard-code file1.C file2.H ...

copyright - Copyright Validation

Check and fix copyright header in source code files. The header is generated based on JINJA templates. A template for HZDR and OpenFOAM Foundation software for C++, shell and dictionaries is shipped with the package. The template name can be specified via --template option. As default the template is expected in the package assets. If you have a need for a custom template, specify the template directory via --template-directory.

Metadata for the header has to be provided via codemeta.json and/or by reuse.toml. The hook tries to load both automatically. The copyright holder for the source code file is generated from the existing header, the copyrightHolder key in codemeta.json and from reuse annotations. In case duplicates exists, they are merged.

Usage:

mpyhooks copyright --template <template> <path/to/file>

keywords - Keyword Validation

Check keyword validity in case metadata.

Usage:

mpyhooks keywords --ref reference.yml case.yml

shellcheck - Check Syntax for Shell Files

Check is based on shellcheck-py, which is a simple wrapper around shellcheck.

Usage:

shellcheck script.sh

The check is part of the hooks collection, because when using it via pre-commit in the default setting in this repository it will check only new and modified files of a fork with respect to a branch containing the current state of the upstream repository.

filesmd - Generate report on new, modified and unchanged files

Compute diff between the active branch and an upstream reference. The diff is stored as FILES.md and contains the information about new, modified, and unchanged files.

Usage:

mpyrpdiff --compare-against upstream-main --report FILES.md

Pre-commit Integration

Detailed installation and usage instructions for pre-commit can be found here.

pip install pre-commit
pre-commit install

Now hooks run automatically on git commit for all stashed files. For running a single hook only use pre commit run <hook>, or for running all hooks on all files pre commit run --all-files, or for running the hooks only on selected files pre-commit run --files .... For more information on pre-commit the reader is referred to its documentation.

Most of the hooks in this repository are setup to run only for new and modified files with respect to a branch containing the current state of the upstream repository (branch name: upstream-main). This is achieved by wrapping the hooks in mpyrpdiff, however, if the branch with the upstream code is not available, all files are checked.

The copyright hooks and shellcheck forward args to their respective command. Their args must end with --, which separates command arguments from the filenames supplied by pre-commit. For example, to use a custom header template shipped with a project:

- id: cpp-copyright
  args: [--template, custom_cpp.jinja, --template-directory, .gitlab/config, --]

For using the hooks in your own repository, create a .pre-commit-hooks.yaml in the root of the repository:

repos:
      - repo: https://codebase.helmholtz.cloud/fwdc/public/python.git
      rev: 5.7.3
      hooks:
          - id: line-length
          - id: preview-encoding
          - id: ifndef
          - id: tabs
          - id: non-standard-code
          - id: cpp-copyright
          - id: shell-copyright
          - id: config-copyright
          - id: keywords
          - id: shellcheck
          - id: filesmd
            args: [--projectname, "My Project Name"]