Introduction to
Version control

Week 5 – Lecture A

Jelmer Poelstra

September 21, 2026

Learning goals

In this lecture, you’ll learn:

  • Why it’s a good idea to use a formal Version Control System like Git for research projects
  • Key Git concepts and terminology such as repositories and commits
  • An overview of the basic Git workflow
  • What GitHub is and how it relates to Git


This lecture covers Git concepts, and we’ll put them into practice in the next one.

Version control: why and how

Keeping track of file versions

During a research project, your files will constantly change. Ideally, you can:

  • Keep earlier versions of your files
  • See what changed between versions
  • Go back to earlier versions (e.g., after an accidental overwrite, or when a script stops working)

Modern cloud storage solutions (OneDrive, Dropbox, etc.) help. You can restore automatically saved earlier versions of individual files, and work simultaneously on files with collaborators.

Why use a Version Control System?

However, a formal Version Control System does this better, and does more. It allows you to:

General benefits

  • Go back to past states of your entire project, not just individual files.
  • See your history of changes.
  • Use it on remote servers like OSC.
  • Publicly (or privately) share your code.
  • Make experimental changes without affecting current functionality.
  • See and undo changes that AI coding assistants made to your code.

Version control is a way to keep your scientific projects tidily organized, collaborate on science, and have the whole history of each project at your fingertips.

— Allesina and Wilmes (2019), Chapter 2

How Git works

Git is the most widely used Version Control System. It maintains a database in which you save “snapshots” of your project with every minor piece of progress.

It manages this cleverly without having to create full copies of the project for every snapshot:

A diagram showing how Git saves project snapshots.

The boxes with dashed lines depict files that have not changed: these will not be saved repeatedly.
Figure from https://git-scm.com.

Key Git term #1: Repository (repo)

A Git repository (or “repo”) is the version-control database for a project.

Organization

  • One Git repository manages files inside a single directory structure.

  • It is typical (and recommended) to have one Git repository for each research project.

To use Git effectively, having separate directories for each project, as discussed in week 2, is important.

Within folders, systematic file organization also makes Git easier to work with.

Practically speaking

  • You can start a Git repository in any dir you have write access to.

  • The database is saved in a hidden dir (.git) in the dir where you started the repo.

A file or dir name that starts with a ., like .git, is hidden.

These don’t show up in file browsers or ls listings by default.

Key Git term #2: Commit

A Git “commit” is a saved snapshot of the project. Note that:

  • You can always go back to the state of the entire project, or of individual files, at any commit.
  • You make commits manually — Git is not an automated backup system, and this is by design!

What to version-control?

You should primarily put manually edited files under version control.
That is, version-control changeable source files, but not derived files. For instance:

  • Version-control your Markdown file, not the HTML it produces.
  • Version-control your script, not the output it produces.

Derived files

Recall from week 2 that results and other derived files in essence are (or should be) disposable,
because they can be regenerated using the raw data and the scripts.

Therefore, version-controlling derived files is usually unnecessary and would lead to bloated repositories.

File limitations

There are some limitations to the types and sizes of files that can be committed with Git:

File type

  • Binary (non-text) files, such as Word or Excel files, or compiled software, can be included, but:

  • Git can’t show line-by-line changes for them like it can for plain-text files.

Repository and file size

  • For performance reasons, it’s best to keep individual repositories <1 GB.

  • Git itself doesn’t limit file sizes, but GitHub (Wednesday) only allows files <100 MB.

Putting it together: what to include

Put under version control

  • Scripts (and any other source code)
  • Project documentation files

And optionally:

  • Metadata (e.g., sample information)
  • Manuscripts (especially when writing in a plain text format)

Don’t put under version control

  • Results
  • Data (in most cases)

More on sharing data

Small datasets may be appealing to add, e.g. because this is an easy way to share them.

That can be OK even if it’s not exactly what Git is designed for — but for large omics datasets, it is often not feasible. Specialized data repositories exist, and we’ll talk about them later in the course.

Quiz: Commit or not?

Your project directory contains the files below. Which ones should you put under version control?

  1. scripts/trim.sh — a script you wrote
  2. results/trim/sampleA.fastq.gz — output from your trimming script
  3. data/sampleA.fastq.gz — raw reads from the sequencing facility
  4. metadata/samples.tsv — a small sample table you typed up
  5. README.html — rendered from README.md
    Click for the answers
  • Correct: a and d: these are files you edit by hand.
  • You should not put b and e (derived files that you can always regenerate from the script or the Markdown file) or c (raw data) under version control.

User Interfaces for Git

Ways to work with Git

  • The native command-line interface (CLI).
  • Third-party graphical user interfaces (GUIs) such as GitHub Desktop.
  • IDEs with Git integration like RStudio and VS Code.

What we’ll use in this course

  • We’ll focus on the CLI because it’s the most universal and powerful interface.

  • You’ll also see the VS Code integration for Git, and you are allowed to use that for e.g. assignments.

Stick with it!

Git takes some getting used to, regardless of the interface — the main difficulties are conceptual, not technical. Many people have “false starts” with it, but in this course we try to get you past that.

This is also an area where Generative AI can be really helpful, once you know the basics!

The basic Git workflow

The three core commands

Git commands always start with git followed by a subcommand or “verb”: git add, git commit, etc. Only three commands tend to make up the vast majority of your Git work:

git add

Does two things:

  1. Start “tracking” files
    (files in your dir are not automatically included in the repo!)
  2. “Staging” files:
    mark changed and new files as ready to be committed.

git commit

Create a new snapshot of the project that includes all currently staged changes.

git status

Get the status of your repo:

  • Which files have changed
  • Which new files are present
  • Tips on next steps, etc.

The workflow and repository visualized

A visual representation of the process of adding and committing changes with Git commands:

A diagram of the process of adding and committing changes with Git commands.

The Git database, which is in a hidden dir .git, is depicted with a gray background.
Files and their changes aren’t automatically added to the database:
you have to explicitly add them with git add and then commit them with git commit.

Remote repositories on GitHub

Git vs. GitHub

Git

  • The version control software that you run on your computer or at OSC.
  • Your repositories are local: each is stored in a project’s .git dir.

GitHub

  • A website that hosts Git repositories online.
  • An online counterpart of a local repo is called a “remote repository” or a “remote”.

A remote on GitHub allows you to:

  • Share your work (e.g., alongside a publication)
  • Have an online backup
  • Collaborate with others

We’ll start using GitHub on Wednesday — create a GitHub account before then!

Keeping local and remote repos in sync

Commit locally as usual, and occasionally upload (“push”) new commits to GitHub with git push:

A diagram of a local repo with one more commit than its GitHub remote.

After making a new commit locally, local and remote repos are out of sync.

A diagram showing git push uploading the new local commit to GitHub.

git push uploads the new commit to GitHub.

A diagram of a local repo and its GitHub remote with the same two commits.

After the push, both repos have the same commits and are back in sync.

Boxes are commits and the 4dce25f-type labels are commit IDs (“hashes”).

Questions?



Click here to continue with today’s hands-on practice: Version control with Git

References

Allesina, Stefano, and Madlen Wilmes. 2019. Computing Skills for Biologists: A Toolbox. Princeton University Press. https://doi.org/10.1515/9780691183961.