Skip to content

Chapter 1 — Introduction

Overview: Why Does a Research Group Need Version Control?

Imagine you have been running simulations for three months. Your code is called analysis_final.py. Then you need to try a new idea, so you create analysis_final_v2.py. Your supervisor asks you to revisit the approach from six weeks ago — but which file was that? You open analysis_final_BACKUP_old.py and analysis_final_v3_THEGOODONE.py and discover they are almost identical, differing by two lines you cannot identify.

This is the version control nightmare, and it happens to every researcher who has not adopted a proper workflow. It costs time, causes errors, and makes published results impossible to reproduce.

Version control is not a programmer's luxury — it is a research tool as fundamental as a lab notebook.

What Goes Wrong Without It

Here are real situations that occur in research groups without version control:

  1. Lost work. A file is accidentally overwritten. The previous version is gone.

  2. Untraceable results. A figure in a submitted paper was generated by run_v4_corrected2.py, but no one remembers exactly which parameters were used at that moment.

  3. Broken collaboration. Two students edit the same file on different computers. One overwrites the other's changes by copying the file via email.

  4. Fear of change. Students avoid refactoring code because "what if something breaks?" Without version control, there is no safe way to experiment.

  5. Irreproducible publications. A reviewer asks for a modified figure. The code that produced the original figure has been changed, and the original cannot be recovered.

All of these problems are solved by version control used correctly.

What This Handbook Covers

This handbook teaches you the one workflow used by this group. It is not a survey of all possible Git workflows. There are many ways to use Git; this handbook teaches one, consistently, because consistency across the group matters more than flexibility.

By the end of this guide, you will be able to:

  • Set up Git and SSH authentication on your machine
  • Clone the group repository
  • Follow the daily development workflow (branch → commit → push → PR)
  • Write meaningful commit messages
  • Open and respond to Pull Requests
  • Resolve merge conflicts
  • Recover from common mistakes

What this handbook does not cover:

  • Advanced Git internals (reflog, filter-branch, bisect)
  • Alternative workflows (Gitflow, trunk-based development)
  • Specific programming languages or scientific computing tools
  • GitHub Actions / CI (introduced briefly in the Maintainer Guide)

How to Use This Handbook

Read the chapters in order the first time. Each chapter builds on the previous one.

Already have some Git experience?

Skim Chapters 1–3 for the group's specific conventions, then work through Chapters 4–11 carefully. Pay special attention to what the group does differently from generic Git tutorials (squash merge, rebase strategy, commit message format).

After your first reading, use this handbook as a reference. The Cheat Sheet (Chapter 17) and FAQ (Chapter 16) are designed for quick lookup.

Every chapter ends with a Checklist and Exercises. Do the exercises — reading about Git without practicing is not sufficient.

Brief Glossary of Terms Used in This Handbook

The full glossary is in the Appendices. These terms appear immediately:

Term Meaning
Repository (repo) A folder tracked by Git, containing all files and their history
Commit A saved snapshot of your changes at a point in time
Branch An independent line of development
Remote A copy of the repository hosted on GitHub
main The primary, protected branch — the official record of the project
Pull Request (PR) A proposal to merge your branch into main, subject to review
Clone Downloading a remote repository to your local machine
Push Uploading your local commits to the remote
Pull Downloading and integrating remote changes into your local branch
Merge Combining two branches
Squash Merge Merging a branch as a single combined commit (the group standard)

Common Mistakes (Chapter 1)

  1. Treating Git as a backup system. Git is a collaboration and history tool. It tracks meaningful changes, not automatic saves.

  2. Committing everything at once at the end. Commit as you work, in logical units.

  3. Using Git only for code. Version control is equally valuable for analysis scripts, parameter files, documentation, and figure-generation scripts.

Best Practice Summary

  • Version control is a research tool, not just a programmer tool.
  • Reproducibility of published results depends on tracking code history.
  • This group uses one canonical workflow — learn it well.
  • Commit early and often, in logical units.
  • The handbook is a living document — suggest improvements via Pull Request.

Checklist

  • I understand why version control matters for research.
  • I understand the difference between Git and GitHub (preview — covered in Chapter 2).
  • I know what this handbook covers and what it does not.
  • I have identified my starting point in the guide.

Exercises

  1. Reflection. Think of one situation in your own research work (past or present) where version control would have prevented a problem. Write one sentence describing it.

  2. Preview. Navigate to the group's GitHub repository in your browser. Look at the list of branches and the commit history on main. You do not need to understand everything yet — just familiarise yourself with what the interface looks like.

  3. Vocabulary. Without looking at the glossary, write your own one-sentence definition of: commit, branch, Pull Request. Compare with the glossary after.