Handling metadata output changes when committing to notebook repositories

What Changed Running notebooks commonly changes:

• execution_count
• saved outputs
• kernel metadata like kernelspec.display_name
• Python version metadata like language_info.version
• sometimes real source cells, which should still be reviewed

Git cannot ignore only parts of a tracked .ipynb with .gitignore.

Use Cases

1. Experimental notebook changes, nothing should be kept

Use Git restore:

git restore 01-Install.ipynb 02-Overview.ipynb 04-Whisper.ipynb 05-Parakeet.ipynb

This discards source edits, outputs, execution counts, and metadata changes.

2. Keep source-cell edits, remove run noise manually

Install tool in repo venv, but do not install the Git filter:

source .venv/bin/activate
pip install nbstripout

Before committing:

nbstripout 01-Install.ipynb 02-Overview.ipynb
git diff
git add 01-Install.ipynb 02-Overview.ipynb

Best when outputs are sometimes intentionally committed.

3. Local automatic stripping for this repo only

Run from repo root, in your venv:

cd /home/yingfeng/transcription-notebooks
source .venv/bin/activate
pip install nbstripout
nbstripout --install

This writes local Git config under .git/config and .git/info/attributes. Do not commit those files. It affects this clone only.

After that, outputs/execution counts are stripped automatically through Git filtering. Real source-cell changes still show up.

Optional metadata stripping:

git config filter.nbstripout.extrakeys 'metadata.language_info.version'

Be careful stripping metadata.kernelspec; that may be useful for other users.

4. Team-wide automatic stripping

Create this file at repo root and commit it:

.pre-commit-config.yaml

Example:

repos:
  - repo: https://github.com/kynan/nbstripout
    rev: 0.7.1
    hooks:
      - id: nbstripout

Each developer runs locally:

pip install pre-commit
pre-commit install

The config file is committed. The actual hook installed in .git/hooks/pre-commit is local and not committed.

5. Sometimes commit curated “good” outputs

Avoid always-on stripping, or bypass it intentionally.

Best workflow:

# For normal cleanup commits
nbstripout notebook.ipynb
git diff
git add notebook.ipynb
git commit

For curated output commits, skip stripping and carefully review:

git diff notebook.ipynb
git add notebook.ipynb
git commit

If using pre-commit and you intentionally want outputs:

git commit --no-verify

About .git/hooks/pre-commit

A custom hook in:

.git/hooks/pre-commit

is local only and not committed. It is fine for personal use, but less shareable than .pre-commit-config.yaml. Also be careful with hooks that run jupyter nbconvert --clear-output --inplace, because they modify files during commit and may wipe curated outputs accidentally.