Stop 13 · Version Control, Git & CollaborationTopics · 2/7

Version Controlling SQL & Notebooks

In short

SQL files are easy to track in Git. Jupyter notebooks are messy, because outputs and images get saved inside them. A few habits keep both clean and reviewable.

Keeping a history of your analysis scripts so you can see what changed, revert mistakes, and collaborate without emailing files back and forth labeled 'final_v3'.

The jaadu signs a thick register at a mess counter beside a brass bell and a steel plate.

Think of it like this

The hostel mess register

In the mess register, the warden signs every menu change: date, what changed, why. Nobody scribbles over old entries. But if cooks also glued their leftover food onto pages, the register would be a mess. Notebook outputs are that leftover food.

Watch it happen

Getting a notebook change into Git cleanly

Edit

Strip output

Diff

Commit

Review

1/5You change a cell in retention.ipynb and rerun it. Charts and tables now sit inside the file.

The big ideas

What you need to know

Keep SQL in .sql files

Queries in their own files are easy to diff, review and reuse. Avoid burying them in dashboards only.

Strip notebook outputs

Outputs bloat files and create huge diffs. Strip them before committing, and rerun to see results.

Never commit data or secrets

Raw data files and passwords go in .gitignore. Once pushed, they're hard to fully remove.

Use a simple folder layout

queries/, notebooks/, data/ (ignored) and a README. Anyone can find things fast.

See it in code

Walk through the code

bash

1pip install nbstripout2nbstripout --install          # strip outputs on every commit3echo "data/raw/" >> .gitignore4echo ".env" >> .gitignore5git add queries/ notebooks/ .gitignore6git commit -m "Add weekly retention query and notebook"7git diff HEAD~1 -- queries/retention.sql

1/3Install nbstripout and hook it into this repo so outputs are removed automatically.

One-time setup for a clean analysis repo, then a normal commit and a quick look at what changed.

Save yourself the pain

Common mistakes

Oops

Committing a 40 MB notebook full of output charts and a CSV of customer data.

Do this instead

Strip outputs, ignore data folders and keep only code and markdown in Git.

Oops

Pushing a notebook with a database password typed into a cell.

Do this instead

Read secrets from environment variables or a .env file listed in .gitignore.

Your mission

Clean up a notebook repo

~25 min

Quick check

Why strip outputs from Jupyter notebooks before committing?

Go deeper

1Set up a repository specifically for your SQL queries or notebooks going forward.
2Learn why notebooks with outputs saved can bloat a Git repo, and how to manage that.
3Practice reverting a file to a previous version using Git history.