Metadata-Version: 2.1
Name: pre-commit-localupdate
Version: 0.7.0
Summary: A CLI tool to automatically update additional dependencies within local hooks in pre-commit configuration files.
Author: M. Farzalipour Tabriz
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Project-URL: source, https://gitlab.mpcdf.mpg.de/tbz/pre-commit-localupdate.git
Requires-Python: <3.15,>=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: packaging>=26.0
Requires-Dist: ruamel-yaml>=0.19.1
Description-Content-Type: text/markdown

# pre-commit-localupdate

A CLI tool to automatically update dependencies in `.pre-commit-config.yaml` files. It specifically targets `additional_dependencies` within local hooks and updates them to the absolute latest stable version. It also adds versions to unversioned packages and pins loosely defined ones to exact versions. You can prevent updating a specific package by adding a `# freeze` comment to its specification line.

This tool parallels the functionality of the `pre-commit autoupdate` command but operates on local hooks. Like `pre-commit autoupdate`, it is meant to be used in supervised mode by developers familiar with software supply chain security.

## Installation

```shell
pip install pre-commit-localupdate
```

## Usage

To check and update the `additional_dependencies` in your `.pre-commit-config.yaml` file, simply run:

```shell
pre-commit-localupdate
```

All options:

```text
usage: pre-commit-localupdate [-h] [--debug] [--dry-run] [-c PRE-COMMIT-CONFIG] [--timeout TIMEOUT]
                              [--request-delay REQUEST_DELAY] [--trusted-env] [--indent-mapping INDENT_MAPPING]
                              [--indent-sequence INDENT_SEQUENCE] [--indent-offset INDENT_OFFSET]
                              [--line-width LINE_WIDTH] [--version]

Automatically update additional dependencies within local hooks in a pre-commit configuration file.

options:
  -h, --help                         show this help message and exit
  --debug                            enable debug logging (default: False)
  --dry-run                          run in dry-run mode: do not update the file and exit with code 1 if an update is
                                     required. (default: False)
  -c, --config PRE-COMMIT-CONFIG     pre-commit configuration file path (default: .pre-commit-config.yaml)
  --timeout TIMEOUT                  network operation timeout in seconds (default: 10)
  --request-delay REQUEST_DELAY      minimum delay between network requests in seconds (default: 1.0)
  --trusted-env                      trust the environment variables
                                     HTTPS_PROXY/ALL_PROXY/NO_PROXY/SSL_CERT_FILE/SSL_CERT_DIR for network connections
                                     (default: False)
  --indent-mapping INDENT_MAPPING    YAML indentation for mappings (default: 2)
  --indent-sequence INDENT_SEQUENCE  YAML indentation for sequences (default: 4)
  --indent-offset INDENT_OFFSET      YAML indentation offset (default: 2)
  --line-width LINE_WIDTH            maximum line width (default: 80)
  --version                          show program's version number and exit

Exit codes: 0: [Success] 1: [Updates required (dry-run)] 2: [Processing error] 3: [Usage error]
```

## Example

Given a `.pre-commit-config.yaml` with the following content:

```yaml
# The file header is preserved. If there is no document start marker (---), it won't be added
---
repos:
  # External hooks won't be touched. Use the 'pre-commit autoupdate' command to update them
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
      - id: end-of-file-fixer
      - id: trailing-whitespace

  - repo: local
    hooks:
      # All comments are preserved
      - id: black
        name: black
        description: "Length of strings is automatically adjusted based on the value of --line-width"
        entry: black
        language: python
        minimum_pre_commit_version: 2.9.2
        require_serial: true
        types_or: [python, pyi]
        additional_dependencies:
          # Loose version definitions are pinned to an exact version
          - "black>=25.1.0"
          # Updates can be prevented by adding a 'freeze' comment to package definitions like the one below
          - "white==0.1.0"  # freeze

      - id: julia-format
        name: format julia code
        description: Unicodeテキストは保持されます。
        language: julia
        types: [julia]
        entry: tools/formatter.jl
        additional_dependencies:
          # Double/single quoting style is preserved and a version is added to packages without a version definition
          - 'JuliaFormatter'

      - id: mdbook-lint
        name: mdbook-lint
        description: rust package to lint markdown
        entry: mdbook-lint lint --fix
        language: rust
        types: [markdown]
        # Updating packages defined in flow style is also supported
        additional_dependencies: ["cli:mdbook-lint"]
```

Running `pre-commit-localupdate` updates the file to the following (with hypothetical latest versions):

```yaml
# The file header is preserved. If there is no document start marker (---), it won't be added
---
repos:
  # External hooks won't be touched. Use the 'pre-commit autoupdate' command to update them
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
      - id: end-of-file-fixer
      - id: trailing-whitespace

  - repo: local
    hooks:
      # All comments are preserved
      - id: black
        name: black
        description: "Length of strings is automatically adjusted based on the value
          of --line-width"
        entry: black
        language: python
        minimum_pre_commit_version: 2.9.2
        require_serial: true
        types_or: [python, pyi]
        additional_dependencies:
          # Loose version definitions are pinned to an exact version
          - "black==26.1.0"
          # Updates can be prevented by adding a 'freeze' comment to package definitions like the one below
          - "white==0.1.0"  # freeze

      - id: julia-format
        name: format julia code
        description: Unicodeテキストは保持されます。
        language: julia
        types: [julia]
        entry: tools/formatter.jl
        additional_dependencies:
          # Double/single quoting style is preserved and a version is added to packages without a version definition
          - 'JuliaFormatter@2.3.0'

      - id: mdbook-lint
        name: mdbook-lint
        description: rust package to lint markdown
        entry: mdbook-lint lint --fix
        language: rust
        types: [markdown]
        # Updating packages defined in flow style is also supported
        additional_dependencies: ["cli:mdbook-lint:0.14.2"]
```

## Supported languages

The following local hook languages are currently supported:

- Go (golang)
- Julia
- Node.js (node)
- Python
- Rust

## Design decisions and limitations

- By design, this tool updates every supported, non-frozen package in local hooks to the absolute latest version.
- Currently, there is no mechanism in place for a release-age cooldown or version range pinning. Without manual verification, the resulting configuration file after each update should be considered untrusted.
- Yanked and pre-release versions are ignored during the latest-version discovery. This means that packages may be downgraded if their latest version is yanked or unpublished.
- During the update, only HTTPS links are fetched from package repositories.
- By default, the [HTTP environment variables](https://www.python-httpx.org/environment_variables/) are ignored. Using the `--trusted-env` flag, you can enable this functionality to set up a proxy or load custom CA certificates.
- If, due to an issue, the latest version of a package cannot be reliably determined, that package is ignored without affecting the script's exit code.
- On Linux/BSD systems, if the permissions (mode/owner/ACL) cannot be set properly, pre-commit configuration files are not updated. This guarantee does not exist for other systems.
- Support for macOS and Windows is on a best-effort basis, and the functionality is not thoroughly tested. Line endings for CRLF files are normalized to LF.
- Non-ACL xattrs may not be properly preserved.
- Symlinks get overwritten and hard links get split after the update.

### Formatting

Significant effort has been made to ensure `pre-commit-localupdate` maintains the original style and preserves comments in pre-commit configuration files. However, since the current version of the underlying library does not perfectly preserve the original YAML file format after processing, `pre-commit-localupdate` automatically folds long string values (like descriptions) and enforces indentation by default when updating files to enhance readability. Both behaviors can be adjusted using command-line parameters.

## Requirements

- `httpx`
- `packaging`
- `ruamel.yaml`

## License

- Copyright 2026 M. Farzalipour Tabriz, Max Planck Institute for Physics (MPP)

All rights reserved.
This software may be modified and distributed under the terms of the GNU Lesser General Public License (LGPL). See the `LICENSE` file for details.
