ci: strip notebook outputs via git filter instead of pre-commit hook

.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

.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

.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:

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

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.*"