Git workflows for transparent research projects
Version Control
Version control is the research notebook for digital work. Git records what changed, when it changed, and why. For open science, that history matters: it helps collaborators understand decisions, recover from mistakes, review contributions, and verify how a project developed over time.
Why this matters
- A Git history makes research, software, documentation, and teaching materials easier to audit.
- Branches and pull requests allow teams to collaborate without overwriting each other’s work.
- Clear commit messages preserve the reasoning behind technical and scholarly decisions.
Organise work around small, reviewable changes
Strong Git practice is not about creating perfect commits; it is about making change understandable. Each branch should have a clear purpose, each commit should describe a meaningful step, and each merge should leave the project in a working state.
- Create a branch for each feature, chapter revision, dataset-cleaning step, or documentation update.
- Commit related changes together instead of mixing unrelated edits.
- Use short but meaningful commit messages, such as `Add survey cleaning script` or `Document interview coding process`.
- Avoid committing generated files, secrets, large raw media, or private participant data unless the project explicitly requires and protects them.
Use pull requests as scholarly review spaces
A pull request is more than a software tool. It is a place to explain what changed, invite questions, show evidence, and record review decisions. Research teams can use pull requests to review code, methods, documentation, analysis scripts, data dictionaries, and manuscript-supporting materials.
- Summarise the purpose of the change and link related issues or tasks.
- List checks performed, such as tests, build commands, sample outputs, or supervisor review.
- Ask reviewers to check the most important risks: interpretation, reproducibility, data handling, or license compatibility.
- Resolve comments with a brief note so future readers understand the decision.
Make the repository easy to audit
An auditable repository allows someone else to move from question to evidence without guessing. That means predictable folders, named scripts, visible dependencies, recorded decisions, and instructions for reproducing important outputs.
- Keep source data, processed data, scripts, documentation, and outputs in clearly named folders.
- Use tags or releases for submitted thesis versions, published datasets, conference demos, or journal article supplements.
- Maintain a changelog for public-facing projects.
- Use `.gitignore` to prevent temporary files, credentials, and local system files from entering the repository.
Practical checklist
- ✓Initialise a Git repository before major writing, coding, or data-cleaning begins.
- ✓Add a README, `.gitignore`, license, and folder guide.
- ✓Use branches and pull requests for collaborative changes.
- ✓Tag important milestones and publication versions.
- ✓Review the repository for secrets and private data before sharing.
Next steps
- Create a branch for your next project change.
- Write a pull request template that asks for purpose, evidence, risks, and checks.
- Tag the next submitted or published version of your project.