From 5521edb2bb4a266c73e1ade3623103df15df3a57 Mon Sep 17 00:00:00 2001 From: Yacine-DH Date: Mon, 13 Apr 2026 15:23:20 +0200 Subject: [PATCH 1/4] docs: add guide for using pixi with lefthook, pre-commit, and prek (#5883) --- docs/integration/third_party/git_hooks.md | 116 ++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 117 insertions(+) create mode 100644 docs/integration/third_party/git_hooks.md diff --git a/docs/integration/third_party/git_hooks.md b/docs/integration/third_party/git_hooks.md new file mode 100644 index 0000000000..d8fdab5325 --- /dev/null +++ b/docs/integration/third_party/git_hooks.md @@ -0,0 +1,116 @@ +# Git Hooks + +When working with `pixi`, you might want to use Git hooks to ensure that your code is formatted and linted properly before committing or pushing it. +Since `pixi` manages your environment, you can use these tools to run your checks within the `pixi` environment, ensuring that everyone on your team is using the same tools and versions without the overhead of downloading duplicate virtual environments. + +We recommend using a Git hook manager to manage your hooks. The most popular ones are [Lefthook](https://github.com/evilmartians/lefthook), [pre-commit](https://pre-commit.com/), and [prek](https://github.com/pavelzw/prek). + +## Lefthook + +[Lefthook](https://github.com/evilmartians/lefthook) is a fast and powerful Git hooks manager for any type of project. + +To use Lefthook with `pixi`, you can add it to your project's dependencies: + +```shell +pixi add lefthook +``` + +Then, initialize and configure `lefthook` by creating a `lefthook.yaml` file in the root of your project: + +```yaml title="lefthook.yaml" +# Run lefthook via pixi +lefthook: pixi run --no-progress lefthook +no_auto_install: true + +# Use template for `run` so we don't have to repeat the flags +templates: + run: run --quiet --no-progress --as-is + +pre-commit: + parallel: true + jobs: + - name: pixi-install + run: pixi install + - group: + parallel: true + jobs: + - name: ruff-check + glob: "*.{py,pyi}" + run: pixi {run} ruff check --fix --exit-non-zero-on-fix --force-exclude {staged_files} + - name: ruff-format + glob: "*.{py,pyi}" + run: pixi {run} ruff format --force-exclude {staged_files} +``` + +Make sure to install the hooks into your Git repository: + +```shell +pixi run lefthook install +``` + +With this configuration, Lefthook will use `pixi run` to execute your hooks, ensuring they run within the correct environment. The `--quiet` and `--no-progress` flags are useful to avoid cluttering the Git output. + +## pre-commit + +[pre-commit](https://pre-commit.com/) is a framework for managing and maintaining multi-language pre-commit hooks. + +You can add `pre-commit` to your project: + +```shell +pixi add pre-commit +``` + +Create a `.pre-commit-config.yaml` file in the root of your project: + +```yaml title=".pre-commit-config.yaml" +repos: + - repo: local + hooks: + - id: ruff-check + name: ruff-check + entry: pixi run --quiet --no-progress ruff check --force-exclude + language: system + types_or: [python, pyi] + require_serial: true + - id: ruff-format + name: ruff-format + entry: pixi run --quiet --no-progress ruff format --force-exclude + language: system + types_or: [python, pyi] + require_serial: true +``` + +Install the `pre-commit` hooks into your repository: + +```shell +pixi run pre-commit install +``` + +By defining the hooks as `local` and `language: system`, `pre-commit` will not try to manage the environments itself, but will instead rely on `pixi run` to execute the commands within the `pixi` environment. + +## prek + +[prek](https://github.com/pavelzw/prek) is a fast, language-agnostic pre-commit hook manager. + +To use `prek`, you can configure it similarly to Lefthook. In your `.prek.toml`: + +```toml title=".prek.toml" +[pre-commit] +parallel = true + +[[pre-commit.jobs]] +name = "ruff-check" +include = ["*.py", "*.pyi"] +command = "pixi run --quiet --no-progress ruff check {staged_files}" + +[[pre-commit.jobs]] +name = "ruff-format" +include = ["*.py", "*.pyi"] +command = "pixi run --quiet --no-progress ruff format {staged_files}" +``` + +Then, you can run the hooks via `pixi`: + +```shell +pixi run prek pre-commit +``` diff --git a/mkdocs.yml b/mkdocs.yml index 0ed7ae944d..8a95ada7cf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -186,6 +186,7 @@ nav: - Pixi Pack: deployment/pixi_pack.md - Pixi Skills: integration/extensions/pixi_skills.md - Third Party: + - Git Hooks: integration/third_party/git_hooks.md - Conda Deny: integration/third_party/conda_deny.md - Direnv: integration/third_party/direnv.md - Starship: integration/third_party/starship.md From 698d28ac77115a4552860baf84d821242a9bec6f Mon Sep 17 00:00:00 2001 From: "M. Yacine Dhouafli" Date: Thu, 16 Apr 2026 17:29:43 +0200 Subject: [PATCH 2/4] Update docs/integration/third_party/git_hooks.md Co-authored-by: Pavel Zwerschke --- docs/integration/third_party/git_hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integration/third_party/git_hooks.md b/docs/integration/third_party/git_hooks.md index d8fdab5325..e5ea3353d8 100644 --- a/docs/integration/third_party/git_hooks.md +++ b/docs/integration/third_party/git_hooks.md @@ -48,7 +48,7 @@ Make sure to install the hooks into your Git repository: pixi run lefthook install ``` -With this configuration, Lefthook will use `pixi run` to execute your hooks, ensuring they run within the correct environment. The `--quiet` and `--no-progress` flags are useful to avoid cluttering the Git output. +With this configuration, Lefthook will use `pixi run` to execute your hooks, ensuring they run within the correct environment. The `--quiet` and `--no-progress` flags are useful to avoid cluttering the output. ## pre-commit From fff482305b936aabc82fceb086ea24c6f432bd40 Mon Sep 17 00:00:00 2001 From: Yacine-DH Date: Thu, 16 Apr 2026 18:42:56 +0200 Subject: [PATCH 3/4] "docs: fix prek URL, rewrite prek section, add pre-commit.ci tipp" --- docs/integration/third_party/git_hooks.md | 50 ++++++++++++++--------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/docs/integration/third_party/git_hooks.md b/docs/integration/third_party/git_hooks.md index e5ea3353d8..350065e298 100644 --- a/docs/integration/third_party/git_hooks.md +++ b/docs/integration/third_party/git_hooks.md @@ -3,7 +3,7 @@ When working with `pixi`, you might want to use Git hooks to ensure that your code is formatted and linted properly before committing or pushing it. Since `pixi` manages your environment, you can use these tools to run your checks within the `pixi` environment, ensuring that everyone on your team is using the same tools and versions without the overhead of downloading duplicate virtual environments. -We recommend using a Git hook manager to manage your hooks. The most popular ones are [Lefthook](https://github.com/evilmartians/lefthook), [pre-commit](https://pre-commit.com/), and [prek](https://github.com/pavelzw/prek). +We recommend using a Git hook manager to manage your hooks. The most popular ones are [Lefthook](https://github.com/evilmartians/lefthook), [pre-commit](https://pre-commit.com/), and [prek]https://github.com/j178/prek . ## Lefthook @@ -88,29 +88,41 @@ pixi run pre-commit install By defining the hooks as `local` and `language: system`, `pre-commit` will not try to manage the environments itself, but will instead rely on `pixi run` to execute the commands within the `pixi` environment. -## prek -[prek](https://github.com/pavelzw/prek) is a fast, language-agnostic pre-commit hook manager. +!!! tip "Using pre-commit in CI" + This approach is **not compatible with [pre-commit.ci](https://pre-commit.ci)**, since `pixi` is not + pre-installed in that environment. + + Instead, run your hooks directly in GitHub Actions using: + + ```shell + pixi run pre-commit run --all-files --show-diff-on-failure + ``` -To use `prek`, you can configure it similarly to Lefthook. In your `.prek.toml`: -```toml title=".prek.toml" -[pre-commit] -parallel = true -[[pre-commit.jobs]] -name = "ruff-check" -include = ["*.py", "*.pyi"] -command = "pixi run --quiet --no-progress ruff check {staged_files}" +## prek -[[pre-commit.jobs]] -name = "ruff-format" -include = ["*.py", "*.pyi"] -command = "pixi run --quiet --no-progress ruff format {staged_files}" +[prek](https://github.com/j178/prek) is a faster, Rust-based, drop-in replacement for `pre-commit`. +It uses the **exact same** `.pre-commit-config.yaml` configuration format, so no changes to your +existing hook definitions are needed. + +To use `prek` with `pixi`, add it to your project: + +```shell +pixi add prek ``` - -Then, you can run the hooks via `pixi`: - + +Install the git hooks: + ```shell -pixi run prek pre-commit +pixi run prek install ``` + +From this point on, `prek` will run your hooks on every commit using your existing +`.pre-commit-config.yaml` — no additional configuration is required. + +!!! tip + If you are already using `pre-commit`, switching to `prek` is as simple as replacing + `pre-commit` with `prek` in your commands. Your existing `.pre-commit-config.yaml` + works without any modifications. \ No newline at end of file From ab0109351f0e3132276653ccfdaa1ef535291c86 Mon Sep 17 00:00:00 2001 From: Yacine-DH Date: Thu, 16 Apr 2026 19:47:56 +0200 Subject: [PATCH 4/4] link fix --- docs/integration/third_party/git_hooks.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/integration/third_party/git_hooks.md b/docs/integration/third_party/git_hooks.md index 350065e298..ea45e56d36 100644 --- a/docs/integration/third_party/git_hooks.md +++ b/docs/integration/third_party/git_hooks.md @@ -3,8 +3,7 @@ When working with `pixi`, you might want to use Git hooks to ensure that your code is formatted and linted properly before committing or pushing it. Since `pixi` manages your environment, you can use these tools to run your checks within the `pixi` environment, ensuring that everyone on your team is using the same tools and versions without the overhead of downloading duplicate virtual environments. -We recommend using a Git hook manager to manage your hooks. The most popular ones are [Lefthook](https://github.com/evilmartians/lefthook), [pre-commit](https://pre-commit.com/), and [prek]https://github.com/j178/prek . - +We recommend using a Git hook manager to manage your hooks. The most popular ones are [Lefthook](https://github.com/evilmartians/lefthook), [pre-commit](https://pre-commit.com/), and [prek](https://github.com/j178/prek). ## Lefthook [Lefthook](https://github.com/evilmartians/lefthook) is a fast and powerful Git hooks manager for any type of project.