How to Use Git for Research Code

Use Git to track research code and record the exact commit that produced a paper’s table or figure.

LanguageEnglish

Decide what belongs in Git

Git records snapshots of selected files. Start by tracking your README, analysis script and data dictionary. The tiny synthetic CSV in this series can be tracked too. For a real study, check permissions before adding data. Use the repository to document how authorized colleagues can get restricted or large inputs.

Put local environments, generated output and temporary files in .gitignore when they can be rebuilt. Check git status before staging files. Ignoring a path works for untracked files, so it cannot remove a file from old commits.

.venv/
__pycache__/
results/

Make the first snapshot

Download the complete study-session sample project, then run the commands below from the extracted study-sessions/ folder. It already contains a README, a data dictionary, a script and a .gitignore.

git init
git status --short
git add README.md .gitignore data/sessions.csv data/data-dictionary.md analysis/analyze.py
git diff --cached
git commit -m "Add study-session data and mean-duration analysis"

git add chooses what goes into the next snapshot, git diff --cached shows those staged changes, and git commit records them. If this is your first Git commit, Git may ask you to configure your name and email. A local commit stays on your machine until you push it.

Record the Git commit behind a paper’s result

When you produce a table for a report, record the full commit ID and any input data version alongside it. The commit is useful only if it includes the changes you actually ran. Check for uncommitted edits and rerun from the intended revision.

git status --short
git rev-parse HEAD
git log --oneline -5

git rev-parse HEAD prints the full ID. Put it in a run note or report appendix so a collaborator can find the revision after the code changes. For example, record the commit beside the quiet-room mean of 25.0 minutes. To inspect the exact script later, replace <commit-id> with the saved ID and run:

git show <commit-id>:analysis/analyze.py

Make one change easy to review

Add a sentence to the README explaining why the sample data are synthetic. Stage only that file, inspect the diff, and commit with a message that describes the change.

See a worked answer
git add README.md
git diff --cached
git commit -m "Explain the origin of the synthetic data"
git log -2 --oneline

References

Adapted from a chapter by The Turing Way Community (CC BY 4.0). Miss Formula reorganized and expanded the explanations and wrote the worked example and exercises.