Git for Researchers: Version Control Without the Fear

Who this is for: Researchers who work with text files — drafts, notes, transcriptions, data extractions — and have heard of git but assumed it was only for programmers. It is not. This document explains why git is useful for text-based research work, and how Claude Code makes it accessible even if you have never used it before.

The problem git solves

You have probably done this:

draft_article.docx
draft_article_v2.docx
draft_article_v2_REVISED.docx
draft_article_v2_REVISED_final.docx
draft_article_v2_REVISED_final_SUBMITTED.docx
draft_article_FINAL_supervisor_comments.docx

Or lost an earlier version of something you later wished you had kept. Or made twenty changes to a document and then wanted to undo just one of them. Or needed to show a collaborator exactly what changed between two versions.

Git solves all of these. It keeps a complete history of every saved state of your files. You can go back to any point. You can see exactly what changed between any two points. You never need to save multiple copies of a file.

Why this matters specifically for Claude Code

When Claude Code modifies files — extracts data, edits a draft, reorganises a folder — it can change many files at once. This is powerful. It is also potentially dangerous:

Without git, some of these situations are irreversible. With git, you commit before a major Claude operation, and if something goes wrong:

> Restore everything to how it was before we started this session.

Claude runs git restore . — everything reverts. Two seconds. Nothing lost.

Git is the undo button for Claude Code sessions.

Five concepts, nothing more

You do not need to understand git deeply. These five concepts cover 90% of research use:

Repository (repo): A folder that git is tracking. You create one with git init. After that, git watches everything in that folder.

Commit: A saved snapshot of your files at a point in time, with a message describing what changed. Like a named save point in a game — you can always return to any commit.

Staging: Before committing, you tell git which changes to include. Usually: all of them.

Diff: The difference between two versions — what was added, what was removed. Essential for seeing what Claude changed.

Restore: Going back to a previous state — a previous commit, or just undoing uncommitted changes.

That is the model. Everything else (branches, remotes, merges) is optional and can be learned when needed.

Setup: starting a git repository

For any project folder you are working in:

cd /path/to/your/project
git init
git add .
git commit -m "Initial commit: project setup"

Done. Git is now tracking this folder. Every file in it is in the history.

In practice, ask Claude to do this:

> Initialise a git repository in this folder.
  Add all current files and make an initial commit with the message
  "Initial commit: [project name] setup"

Claude runs the commands. You do not need to type them.

The daily rhythm: commit as checkpoint

The core habit: commit before you ask Claude to do anything significant.

> Before we start: commit all current files with the message
  "Checkpoint before extraction session [today's date]"

Then Claude does its work. Afterwards:

> Show me what changed in this session.

Claude runs git diff HEAD~1 — you see every line added or removed across every file. You review. If it looks right:

> Commit everything with the message "Extracted persons from registers 1–15"

If something went wrong:

> Restore all files to the state before this session.

Claude runs git restore . — everything reverts to the last commit.

What commit messages are for

A commit message is a note to your future self (and collaborators) about what happened and why. Written well, git log becomes a research diary:

2025-04-07  Initial commit: Montaillou project setup
2025-04-08  Added 12 source PDFs and converted to markdown
2025-04-09  First-pass extraction: persons from registers 1–8
2025-04-10  Revised extraction conventions — added [?] for uncertain names
2025-04-11  Completed person extraction registers 1–20, 487 entries
2025-04-14  Updated CLAUDE.md: added date conversion rule
2025-04-15  Restructured output folder; moved raw extractions to /archive
2025-04-18  Draft section 2 — argument restructured after supervisor meeting

This is a complete record of what was done, when, and in what order. No separate log file needed. git log shows it instantly.

Ask Claude to write commit messages:

> Commit today's work. Write a commit message that describes what we did
  in this session, based on what you know we changed.

Claude writes a meaningful message based on what actually happened.

Seeing what changed: git diff

After any Claude session, before committing:

> Show me what changed since the last commit.

Claude runs git diff and summarises the output. You see:

This is how you verify Claude did what you intended. For a data extraction session, you check that the CSV grew in the expected way. For a draft editing session, you check that Claude's changes match your instructions. For a file reorganisation, you check that nothing was lost.

Never commit without reviewing what changed. The diff is your quality control.

Going back: restore and reset

Undo all uncommitted changes (go back to last commit):

> Restore all files to the last commit. Discard everything since then.

Claude runs git restore .

Restore a single file:

> Restore extractions.csv to how it was at the last commit.
  Keep all other changes.

Claude runs git restore extractions.csv

Go back to an older commit (view the history first):

> Show me the commit history for this project.

Claude runs git log --oneline — you see a list like:

a3f8c21 Completed person extraction registers 1–20
7d2b104 Revised extraction conventions
c19e3a5 First-pass extraction registers 1–8

> Go back to the state at commit c19e3a5 — the first-pass extraction.
  I want to see what the data looked like before the revision.

Claude can show you that state or help you recover specific files from it.

Practical patterns for research work

Before a risky Claude operation

Any time Claude is about to do something significant — batch processing, reorganising files, modifying many documents — commit first:

> Commit everything as it is now with the message "Pre-session checkpoint [date]"
  Then proceed with [task].

The checkpoint is your fallback. If the operation goes wrong, you restore. If it goes right, you commit the result with a descriptive message.

Tracking draft evolution

Stop saving draft_v2_FINAL.docx. Work in a single file (draft.md or draft.docx), commit every meaningful revision:

> Commit the current draft with the message:
  "Draft: restructured introduction, added section 3 skeleton"

To see how the introduction has changed over time:

> Show me how the introduction section has changed across the last 5 commits.

Claude runs git log -p -- draft.md filtered to that section.

Protecting source files

Put your original source materials (PDFs, raw transcriptions) in a /sources/ folder. After the initial commit of those files, tell Claude:

> The files in /sources/ are originals — never modify them.
  Always write outputs to /output/ or /extractions/.

Also add to CLAUDE.md:

## File conventions

- /sources/ — original files, read-only, never modify

- /output/ — processed outputs, write here
Git is active in this repo. Commit regularly.

If Claude ever touches /sources/ unintentionally, git diff will show it immediately.

Shared project with a collaborator

Both researchers clone the same repository. Each works in their own branch or takes turns on main. CLAUDE.md, skills, and conventions are shared — everyone gets them when they pull.

# Collaborator A pushes their extractions
git add extractions/
git commit -m "Added registers 21–35 extractions"
git push

# Collaborator B pulls and continues
git pull
# Now has A's work; continues with registers 36–50

Claude Code handles all these commands when asked:

> Pull the latest changes from the shared repository, then show me
  what my collaborator added since I last synced.

What Claude can do with git — so you don't have to

Claude Code has full git capability via the Bash tool. In practice, this means you can use git entirely in plain English:

What you say What Claude does
"Commit everything with a good message" git add -A && git commit -m "[writes message]"
"What changed since yesterday?" git log --since=yesterday + git diff
"Show me the history of this file" git log --follow -- filename
"Undo what we just did" git restore .
"Go back to last week's version of the draft" git log → identify commit → git checkout [hash] -- draft.md
"What did my collaborator change?" git log origin/main..HEAD or git diff origin/main
"Is there anything uncommitted?" git status

You do not need to remember any of this syntax. You describe what you want; Claude translates.

Setting up git: one-time steps

Mac: Git is already installed. Open Terminal and type git --version to confirm.

Windows (native): Download Git for Windows from git-scm.com. During install, accept all defaults.

Windows (WSL): Git is available in Ubuntu:

sudo apt-get install git

First-time configuration (do this once, any terminal):

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

This signs your commits. Ask Claude to run these if you prefer:

> Configure git with my name [name] and email [email].

GitHub (optional): If you want to back up your repository online or share with a collaborator, create a free account at github.com and ask Claude to connect your local repository to it:

> I have a GitHub account. Help me create a repository there
  and push this project to it.

What git is not

Not a backup system. Git tracks history but stores it on your machine. For actual backup, push to GitHub or another remote, or use your normal backup solution alongside git.

Not required for Claude Code. Claude Code works fine without git. Git is an additional safety layer that becomes more valuable the more Claude modifies your files.

Not complex to start. The five commands for 90% of use — git init, git add, git commit, git diff, git restore — are all things Claude can run for you. You understand the concepts; Claude handles the syntax.

Related