GitLocker: The Coding Marketplace

Description:

precommitupdate 0.4.0.post1

pre-commit-update

pre-commit-update is a simple CLI tool to check and update pre-commit hooks.

Table of contents

Reasoning
Features
Installation
Usage

Pipeline usage example

GitLab job

pre-commit hook usage example

Configuration

1. Reasoning
pre-commit is a nice little tool that helps you polish your code before releasing it into the wild.
It is fairly easy to use. A single pre-commit-config.yaml file can hold multiple hooks (checks) that will go through
your code or repository and do certain checks. The problem is that the file is static and once you pin your hook versions
after a while they get outdated.
pre-commit-update was created because there is no easy way to update your hooks by using
pre-commit autoupdate as it is not versatile enough.
2. Features

Feature
pre-commit-update
pre-commit autoupdate

Dry run (checks for updates, does not update)
Yes
No

Stable versions only
Yes
No

Exclude repo(s) from update check
Yes
Workaround (updates only specified repo(s))

Keep repo(s) (checks for updates, does not update)
Yes
No

Update by hash instead of tag
Yes
Yes

Can be used as a pre-commit hook
Yes
No

Can be configured in pyproject.toml
Yes
No

3. Installation
pre-commit-update is available on PyPI:
$ python -m pip install pre-commit-update

NOTE: Please make sure that git is installed.
4. Usage
pre-commit-update CLI can be used as below:
$ pre-commit-update [OPTIONS]

Option: Short description:

-d, --dry-run / -nd, --no-dry-run Checks for the new versions without updating
if enabled [default: nd]

-a, --all-versions / -na, --no-all-versions Includes the alpha/beta versions when
updating if enabled [default: na]

-v, --verbose / -nv, --no-verbose Displays the complete update output if
enabled [default: nv]

-w, --warnings / -nw, --no-warnings Displays warning messages if enabled [default: w]

-p, --preview / -np, --no-preview Previews the cli option values by the
overwriting order if enabled (disables the
actual cli work!) [default: np]

-e, --exclude REPO_URL_TRIM Exclude specific repo(s) by the repo url
trim - use '*' as a wildcard

-k, --keep REPO_URL_TRIM Keep the version of specific repo(s) by the
repo url trim (still checks for the new
versions) - use '*' as a wildcard

-b, --bleeding-edge REPO_URL_TRIM Get the latest version or commit of specific
repo(s) by the repo url trim - use '*' as a
wildcard

-h, --help Show this message and exit.

Below you can find more detailed explanations of how each option works.
Some of the options (--exclude, --keep and --bleeding-edge) use REPO_URL_TRIM as an argument.
Example of the REPO_URL_TRIM: https://github.com/ambv/black -> black (you will only pass black as a parameter to the
--exclude, --keep or --bleeding-edge option)

-d, --dry-run / -nd, --no-dry-run - If enabled, updates will be fetched, but they won't be applied. Useful if you are only
curious about potential changes that would occur.

-a, --all-versions / -na, --no-all-versions - If enabled, all version tags will be checked. This may include alpha, beta
or release candidate versions. Keep in mind that this option is not the same as -b, --bleeding-edge!

-v, --verbose / -nv, --no-verbose - If enabled, every detail will be printed out once the process completes. This
does not display warnings if they are disabled (-nw, --no-warnings)!

-w, --warnings / -nw, --no-warnings - If enabled, various validation warnings will be displayed (mostly configuration issues)

-p, --preview / -np, --no-preview - This option excludes all other options if enabled! It is used in order to display the
configuration priorities/overwrites between default configuration, pyproject.toml configuration and options passed directly
to the cli. It also displays the final configuration and what was changed.

-e, --exclude - This option, if used, excludes the complete repo (along with all the hooks) from update check. That means that the given
repo url (for the given REPO_URL_TRIM) will be completely skipped. You can exclude multiple repos by repeating the option multiple times
(example: --exclude black --exclude isort). You can also use a wildcard * (example: --exclude '*') in order to exclude every single repo
from the update process. This is useful when, for example, your python version is not up-to-date, and you need time to upgrade your code before
updating your hooks to their latest versions.
NOTE - Using a wildcard with the --exclude option disables the --keep and bleeding-edge options

-k, --keep - This option, if used, keeps the current repo version/hash (along with all the hooks). That means that the given
repo url (for the given REPO_URL_TRIM) will fetch available updates and display them, but no update will take place. You can keep multiple
repos by repeating the option multiple times (example: --keep black --keep isort). You can also use a wildcard * (example: --keep '*')
in order to keep every single repo pinned to the current version while also checking for updates.
NOTE - Using a wildcard with the --keep option disables the --exclude and bleeding-edge options

-b, --bleeding-edge - This option, if used, gets the latest repo version/hash (whatever is more recent). That means that the given
repo url (for the given REPO_URL_TRIM) will be updated to the latest tagged version OR latest commit, depending on which one is more recent. This
also means that --bleeding-edge option ignores the --all-versions option - it will always fetch the latest update - stable or not.
You can set multiple repos as --bleeding-edge by repeating the option multiple times (example: --bleeding-edge black --bleeding-edge isort).
You can also use a wildcard * (example: --bleeding-edge '*') in order to update every single repo to the latest version/hash.
NOTE - Using a wildcard with the --bleeding-edge option disables the --exclude and keep options

-h, --help - Displays all the available options along with the short description of each.

1) Pipeline usage example
a) GitLab job:
pre-commit-hooks-update:
stage: update
script:
# install git if not present in the image
- pip install pre-commit-update
- pre-commit-update --dry-run
except:
- main
when: manual
allow_failure: true

NOTE: This is just an example, feel free to do your own configuration
2) pre-commit hook usage example
You can also use pre-commit-update as a hook in your pre-commit hooks:
- repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
rev: v0.4.0 # Insert the latest tag here
hooks:
- id: pre-commit-update
args: [--dry-run, --exclude, black, --keep, isort]

NOTE: This is just an example, feel free to do your own configuration
5. Configuration
You can configure pre-commit-update in your pyproject.toml as below (feel free to do your own configuration):
Example:
[tool.pre-commit-update]
dry_run = true
all_versions = false
verbose = true
warnings = true
preview = false
exclude = ["isort"]
keep = ["black"]
bleeding_edge = ["pylint"]

NOTE: If some of the options are missing (for example --exclude option), pre-commit-update
will use the default value for that option (default for --exclude option would be an empty list).
IMPORTANT If you invoke pre-commit-update with any options (e.g. pre-commit-update -d),
pyproject.toml configuration will be overridden. This means that all the options passed while
calling pre-commit-update will have priority over the configuration defined inside pyproject.toml.
If you want to override boolean options, you can do so by passing the negative option value.
For example, given the configuration above, to override --verbose option from pyproject.toml, you
would invoke pre-commit-update with either --no-verbose or -nv.
You can always check the configuration overrides (priorities) by running pre-commit-update -p / pre-commit-update --preview