Version Control for Researchers: Managing Scientific Code with Git

Set Up Your Repository

A Git repository is a directory whose contents are tracked by Git. To start tracking a new project, run git init in the project directory. This creates a hidden .git directory that stores the entire history of the project. For an existing project on GitHub or GitLab, git clone downloads the repository and its history to your local machine.

Create a .gitignore file that lists files and patterns that Git should not track. For scientific projects, this typically includes compiled binaries, large data files, temporary output, log files, and editor-specific files. A well-maintained .gitignore keeps the repository clean and focused on the source files that actually matter.

Push the repository to a remote hosting service like GitHub, GitLab, or Bitbucket. This provides a backup (your work survives even if your laptop is lost), enables collaboration (colleagues can access and contribute to the code), and makes sharing straightforward (reviewers and readers of your papers can examine the code). For private research before publication, all major hosting services offer free private repositories.

Include a README file at the top level that describes the project, lists dependencies, and provides instructions for running the code. A LICENSE file specifies the terms under which others can use your code. The MIT License and Apache License 2.0 are common permissive choices for scientific software.

Develop a Commit Workflow

A commit is a snapshot of the project at a specific point in time. Good commit practice means making commits that are small, logical, and well described. Each commit should represent a single coherent change: adding a new analysis function, fixing a bug in data loading, or updating a plot format. Avoid commits that mix unrelated changes.

Write commit messages that explain the purpose of the change, not just what was changed. "Fix off-by-one error in boundary condition loop" is much more useful than "Fixed bug" or "Updated code." For scientific code, it is helpful to reference the specific analysis, figure, or experiment that motivated the change. Months or years later, these messages serve as a lab notebook for your computational work.

Use git status to see which files have been modified, git diff to see the specific changes, git add to stage changes for the next commit, and git commit to record them. The staging area allows you to select exactly which changes to include in each commit, even if multiple files have been modified for different reasons.

Commit frequently. A good rhythm is to commit every time you complete a logical unit of work, whether that takes 15 minutes or a few hours. Long gaps between commits increase the risk of losing work and make the history harder to understand. If you need to experiment freely, use branches (described in the next step) rather than accumulating uncommitted changes.

Use Branches for Experiments

A branch is an independent line of development. The main branch (typically called main or master) should contain code that is tested and validated. When you want to try a new numerical method, explore an alternative analysis approach, or refactor a section of code, create a new branch. This keeps the main branch stable while giving you freedom to experiment.

Create a branch with git checkout -b new-method-test. Work on the branch, making commits as usual. If the experiment succeeds, merge the branch back into main with git merge new-method-test. If it fails, delete the branch without affecting main. The history records both the experiment and its outcome, which is valuable documentation even for approaches that did not work.

For collaborative projects, branches enable multiple researchers to work on different aspects simultaneously. Each person works on their own branch and merges into main when their work is complete and tested. Pull requests (on GitHub) or merge requests (on GitLab) provide a formal review process where colleagues can examine proposed changes, suggest improvements, and approve them before they enter the main branch.

Tag and Archive for Publications

When you submit a paper or produce results for a presentation, create a Git tag marking the exact version of the code used. Tags are named pointers to specific commits. Use descriptive tag names like paper-v1-submission or nature-2026-revision. Unlike branches, tags do not move when new commits are made, providing a permanent reference to a specific code state.

For long-term archival and citability, deposit a tagged version of the repository on Zenodo. Zenodo integrates directly with GitHub: when you create a release on GitHub, Zenodo automatically archives a snapshot and assigns a DOI (digital object identifier). This DOI can be included in your paper, ensuring that readers and reviewers can access the exact code used to produce your results, permanently.

Include in your paper or supplementary material the Git commit hash (a unique identifier for the exact code version), the DOI of the archived code, and any necessary instructions for reproducing the results. Many journals now require or strongly encourage this level of computational transparency.