From ad69d9e0bb2a306f0eb698552ff8877dcd5ede00 Mon Sep 17 00:00:00 2001
From: Marius Lange <marius.lange@bsse.ethz.ch>
Date: Mon, 22 Jun 2026 14:39:54 +0200
Subject: [PATCH] ci: strip notebook outputs via git filter instead of
 pre-commit hook

Replaces the in-place nbstripout pre-commit hook (which stripped the working
copy on every commit) with the nbstripout git *filter*: outputs are stripped
from the committed blob while staying in the working tree, so notebooks stay
rendered locally. Set up per clone via the bundled `install-hooks` task;
enforced in CI with `nbstripout --verify`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .gitattributes              |  4 ++++
 .github/workflows/lint.yaml |  2 ++
 .pre-commit-config.yaml     |  4 ----
 README.md                   | 14 +++++++++++++-
 pixi.toml                   |  1 +
 5 files changed, 20 insertions(+), 5 deletions(-)
 create mode 100644 .gitattributes

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..8b431fc
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,4 @@
+# Strip Jupyter notebook outputs on the way into git, while keeping them in your
+# working copy. Activate once per clone with `pixi run install-hooks`.
+*.ipynb filter=nbstripout
+*.ipynb diff=ipynb
diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
index 3b16cae..e5750c6 100644
--- a/.github/workflows/lint.yaml
+++ b/.github/workflows/lint.yaml
@@ -25,3 +25,5 @@ jobs:
           cache: true
       - name: Run pre-commit checks
         run: pixi run pre-commit run --all-files
+      - name: Verify notebooks contain no outputs
+        run: git ls-files -z '*.ipynb' | xargs -0 -r pixi run nbstripout --verify
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 9ee03db..e33f882 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -23,10 +23,6 @@ repos:
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
         types_or: [python, pyi, jupyter]
-  - repo: https://github.com/kynan/nbstripout
-    rev: 0.9.1
-    hooks:
-      - id: nbstripout
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:
diff --git a/README.md b/README.md
index 66d7cb9..50ab3fd 100644
--- a/README.md
+++ b/README.md
@@ -64,10 +64,15 @@ Before installing the environment, update these files with your project details:
 
 ```bash
 pixi install                   # create environment from pixi.toml
-pixi run pre-commit install    # set up code quality hooks
+pixi run install-hooks         # pre-commit hooks + notebook output-stripping filter
 pixi run install-kernel        # register Jupyter kernel
 ```
 
+> `install-hooks` also sets up the [nbstripout](https://github.com/kynan/nbstripout)
+> git filter. Notebook outputs are then stripped from commits automatically while
+> staying in your working copy. **Run it once in every clone** (including remote
+> servers and worktrees), or outputs may slip into git.
+
 💡 **Tip**: Use `pixi shell` to enter the environment interactively—then you can run commands directly without the `pixi run` prefix.
 
 ### Step 5: Verify your setup
@@ -188,6 +193,13 @@ This template uses **pre-commit hooks** to automatically check your code before
 | [Biome](https://biomejs.dev/) | Formats JSON/JSONC files |
 | [pyproject-fmt](https://github.com/tox-dev/pyproject-fmt) | Formats `pyproject.toml` |
 
+**Notebook outputs** are handled separately by an [nbstripout](https://github.com/kynan/nbstripout)
+git *filter* (not a pre-commit hook), set up by `pixi run install-hooks`. The filter
+strips outputs from the committed copy while leaving them in your working tree, so
+your notebooks stay rendered locally but git history stays clean. CI fails the build
+if a notebook with outputs ever lands in the repo (a clone that skipped
+`install-hooks`), via `nbstripout --verify`.
+
 Hooks run automatically on `git commit`. To run manually:
 
 ```bash
diff --git a/pixi.toml b/pixi.toml
index 5546115..3ac819c 100644
--- a/pixi.toml
+++ b/pixi.toml
@@ -13,6 +13,7 @@ extra-index-urls = ["https://pypi.nvidia.com"]
 lab = "jupyter lab"
 test = "pytest"
 install-kernel = "python -m ipykernel install --user --name=analysis-template --display-name='Analysis Template (Pixi)'"
+install-hooks = { cmd = "pre-commit install --install-hooks && nbstripout --install && git config diff.ipynb.textconv 'nbstripout -t'", description = "Install pre-commit hooks + the nbstripout notebook-output filter (run once per clone)" }
 
 [dependencies]
 python = "3.12.*"