plot_determinant_stack(
captures = c('Analysis code'),
title = 'Version control captures the analysis code; later chapters capture the rest')
Maintaining a high degree of transparency in scientific reporting is essential not just for gaining trust and credibility within the scientific community but also for facilitating the development of new ideas.
Karthik Ram, Git Can Facilitate Greater Reproducibility and Increased Transparency in Science (2013)
This chapter has three practical aims. By its end you will be able to write a commit history that answers ‘what changed and why’ for any analysis you run. You will be able to build a .gitignore that keeps protected health information out of a repository before the first commit rather than after a breach. Finally, you will be able to state exactly which single rung of the reproducibility ladder a GitHub URL has actually earned, and which it has not.
We begin by placing version control on the determinant stack and naming the failure it cures. We then set out the analyst’s three judgments, the git model, and the reading of a history, before turning to what must never be committed. Branches, the undoing of mistakes and merge conflicts, and remotes follow, and we close the exposition with what git does not do. A worked example, a note on collaborating with an LLM, and the exercises complete the chapter.
Version control is this book’s clearest case of pure capture at the very top of the determinant stack. Figure 4.1 marks the layer it secures. Before a repository exists, the analysis code is not merely unpinned; it is not reliably even locatable by anyone but the analyst who wrote it. Placing it under git, and pushing it to a remote, is the single act that lifts that top layer from nothing to L0. The input-data layer directly beneath it is deliberately left unhighlighted here, because this chapter’s central judgment runs the other way. Health data, unlike code, often must be kept out of the very history that pins everything else. That is the subject of the section on .gitignore below.
plot_determinant_stack(
captures = c('Analysis code'),
title = 'Version control captures the analysis code; later chapters capture the rest')
If we open the folder of almost any analysis that has run for more than a month without version control, the same artifact greets us. There is analysis.R, and beside it analysis_v2.R, analysis_final.R, analysis_final_v2.R, and, inevitably, analysis_final_v2_FINAL.R. A dated copy or two, analysis_2025-03-14.R, sits among them, and a analysis_reviewer.R from the week the referee reports came back. Every file is a manual snapshot, taken because the analyst feared to overwrite a version that worked. The scheme fails in three ways at once. It does not say which file produced the figure in the submitted manuscript. It does not say what differs between any two of them, so recovering a change means reading both side by side. And it does not say why any change was made, because the reason lived in the analyst’s head and is now gone.
This is the failure that version control exists to cure. What, then, is the cure? A tidier naming scheme will not do; the cure is a different object. A version-control system keeps a single working copy of each file. It records, as a separate and complete history, every state that copy has passed through, together with a note on each change saying what it was and why it was made. The drawer of copies collapses back into one analysis.R, and each copy becomes an entry in a history that can be read, searched, and, if need be, restored. The tool that has won this role, across the sciences and across software of every kind, is git. The service that most often hosts a git history on the network is GitHub, with GitLab its principal institutional sibling. This chapter teaches both from first principles. Version control is the single most universally taught element of a modern reproducibility course, and it is the foundation on which the rest of this book stands.
It is also the foundation in a precise, technical sense. The next chapter, Chapter 5, makes the compendium the unit of reproducible work, and Chapter 3 placed the bare compendium at the bottom rung of the ladder, L0 locatable. The artifact that marks L0 is exactly a version-controlled repository. That is, an analysis is locatable when, and only when, it is under version control and can therefore be found, read, and referred to by a second person. Everything the later chapters add is installed on top of a version-controlled history: the lockfile of Chapter 6, the container of Chapter 7, the continuous integration of Chapter 12.
Version control automates the mechanics of history perfectly and automates none of the judgment that makes a history useful and safe. Three decisions belong to the analyst and are the subject of this chapter as much as the commands are.
Deciding what must never be committed. A commit is, by design, permanent and copied to every clone of the repository. The judgment of what may safely be made permanent and public, and what must be kept out of the history entirely, is the analyst’s. In health research it is a judgment with legal and ethical force. Protected health information, identifiable data, and credentials must never enter the history. As we shall see, deleting them in a later commit does not remove them from it. This is the first and gravest of the three judgments.
Choosing the granularity and the message of a commit. A commit is a unit of change. How much change it should contain, and what its message should say, are matters of craft that no tool decides. A history of one enormous commit reading ‘did the analysis’ is almost as useless as no history at all. A history of small, coherent commits whose messages say why each change was made is a readable record of decisions.
Deciding when to branch and when to tag. Whether a piece of work warrants a branch of its own, and whether a particular state of the analysis warrants a permanent tag, are design decisions about the shape of the history. They are cheap to make and expensive to omit. The state of the code at the moment a manuscript was submitted is worth a tag, and no tool will place it for the analyst.
New terms are defined again on first use; they are collected here for reference.
.git subdirectory. A clone is a complete copy of a repository, history and all.git add, to go into the next commit. Staging lets a commit hold a chosen subset of the current changes..gitignore. A file listing path patterns that git should not track, used to keep derived outputs, large data, and, above all, sensitive files out of the history.main, although git itself still names it master unless told otherwise, as with git init -b main.origin is the conventional name of the primary remote.The value of a version-control system is easiest to state as the negation of the FINAL-file failure. That failure loses three things, and version control restores each.
It loses the identity of the working version. With a drawer of dated copies, no file is authoritative. With git, there is one analysis.R, and its history holds every prior state, so the question ‘which version is current’ cannot arise. It loses the content of each change. Two snapshot files differ in ways that can be recovered only by comparing them line by line by hand. A git history presents each change as a diff, a precise statement of the lines added and removed. Git computes the diff on demand from the snapshots it stores, since git keeps full snapshots, not diffs. Lastly, it loses the reason for each change, the single most valuable and most perishable piece of information about an analysis. Why was the outlier-exclusion threshold changed from three standard deviations to two? A dated file cannot say. A commit whose message reads ‘Tighten outlier threshold to 2 SD per reviewer 2’s comment’ says exactly why, and the record stays with the code.
The recorded reason is what makes version control an instrument of scientific accountability. A computational result is the end of a chain of decisions, each of which could have gone otherwise. In a regulated analysis, a clinical trial subject to audit, a study destined for a guideline, the chain of decisions is itself an object of scrutiny. ‘Why did the estimate change between the interim and the final analysis’ is a question an auditor is entitled to ask and the analyst is obliged to answer. A commit history in which each change carries its reason is most of the answer, already written, dated, and attributed. It is, however, a record of what the committers asserted, not a regulated audit trail. The next section explains the difference.
Git is often taught as a list of commands to memorize, which is why it is so often found bewildering. It is far better understood as a small and coherent data model, after which the commands follow naturally. There are three ideas.
The first is the repository. A git repository is an ordinary directory, the analyst’s project, that git has been told to track. Git then maintains, in a hidden .git subdirectory, the complete history of everything under that directory. The ordinary files the analyst edits are the working tree; the .git directory is the history. Creating a repository is a single command run once in the project directory.
cd diabetes-cohort
git init -b mainThe -b main names the first branch main; without it, git as of version 2.56 names it master, and the git push -u origin main commands later in this chapter would then fail. The git preflight of the setup appendix (Git preflight) sets main as the default once per machine, together with the name and e-mail address every commit records. It is worth running before this chapter’s first command.
The second idea, and the central one, is the commit. A commit is a snapshot of the tracked files at one moment, recorded together with four things: who made it, when, a message describing it, and a hash that names it. That hash is a forty-character SHA-1 string, usually shown in an abbreviated form such as a1b2c3d. It is computed over the whole commit object, and the snapshot alone does not determine it. The commit object references the snapshot, folds in the metadata, and records the hash of the commit before it. (Git also supports repositories that use the longer SHA-256 hash of sixty-four characters, though SHA-1 remains the default.) Because each commit’s hash incorporates its parent’s, the history is a chain. No past entry can be altered without changing its hash and the hash of every commit after it. The hashes are, for practical purposes, unique, and git guards against the known SHA-1 collision attacks with built-in collision detection. The chain makes a history tamper-evident in a narrow sense. Anyone who recorded a commit’s hash, in a tag, a manuscript, or a colleague’s clone, can detect that the history leading to it was later changed.
But how much evidence is tamper-evidence? It is weaker than it sounds, and anyone headed for regulated work should know exactly how much weaker. The author’s name and e-mail address, and both dates a commit carries, are whatever the committer’s own git client supplies. Setting GIT_AUTHOR_DATE and GIT_COMMITTER_DATE and passing --author produces a commit under another person’s name dated years in the past, which git accepts without complaint.
GIT_AUTHOR_DATE='2019-03-01T09:00:00' \
GIT_COMMITTER_DATE='2019-03-01T09:00:00' \
git commit --author='Someone Else <someone@example.org>' \
-m 'Backdated commit'History is also rewritable by design. git commit --amend, git rebase, and git filter-repo all replace commits with new ones, and in a repository the analyst controls nothing prevents it. The hash chain detects a rewrite only for someone holding an earlier hash to compare against. Assurance is added from outside the commit. One source is commits signed with a key bound to a verified identity. Another is a forge configured to protect the main branch against force-pushes and to log pushes, reviews, and merges on its own servers with its own clock. Even then, a git history is not, by itself, the audit trail that FDA’s regulations require of electronic records in the studies they cover. That trail must be secure, computer-generated, and time-stamped, and must record operator actions independently (21 CFR Part 11, n.d.). Within those limits, a well-kept history is an honest and very useful record of how an analysis was built. The rest of this chapter treats it as that.
The third idea is the history itself, the chain of commits, each pointing back to its parent, running from the first commit to the most recent. Reading that chain is reading the story of how the analysis came to its current state. A branch, which we treat below, is nothing more than a movable name pointing at one commit in this structure.
The everyday cycle of work has just two steps against this model. They exist because git deliberately separates choosing what goes into a commit from making the commit. First one stages the changes to be recorded, with git add; then one commits the staged changes, with git commit, attaching the message. The staging step is not ceremony. It lets a single commit hold a coherent subset of the work in progress, so that an afternoon’s editing across several concerns can be recorded as several focused commits.
# edit analysis.R, then see what has changed
git status
# stage the file for the next commit
git add analysis.R
# record the staged change with a message
git commit -m "Add Cox model for 30-day readmission"The message is the part of a commit that carries the scientific value. The convention, which merits adoption from the first day, is a short imperative summary line of about fifty characters. It is optionally followed by a blank line and a paragraph giving the why. ‘Fix bug’ is a wasted message. ‘Correct person-time denominator to exclude pre-enrollment follow-up’ is a message that will still be intelligible, and still exculpatory, at an audit three years later.
Once a history exists, how do we read it? A history that cannot be read is of little use, and git provides two complementary views of it. The log is the list of commits, most recent first, each with its hash, author, date, and message. It is the table of contents of the analysis’s development.
# the full log
git log
# a compact one-line-per-commit view
git log --oneline
# which commits touched analysis/scripts/
git log --oneline -- analysis/scripts/In a scratch copy of the worked example below, three commits in, the compact view reads as follows. Each line is the abbreviated hash and the summary line of the message, most recent first.
# output abridged, from git 2.56.0
git log --oneline
#> c7d4711 Tighten outlier threshold to 2 SD per reviewer 2
#> a9aa55f Add cleaning script for registry extract
#> 936e050 Initialize compendium and .gitignoreThe diff is the complementary view. Where the log lists the changes, the diff gives the content of one. git diff shows the changes in the working tree that have not yet been staged. git show displays the full diff of any single commit named by its hash, and git diff between two commit hashes shows everything that changed between them.
# what have I changed but not yet staged?
git diff
# show one commit's changes in full
git show a1b2c3d
# what changed between two points in the history?
git diff a1b2c3d f4e5d6cHere is the diff from the same scratch repository, taken just before the third commit, when one line of the cleaning script had been edited. A line beginning - is the committed version and a line beginning + is its replacement. The unmarked lines are context, and the @@ header gives their position.
# output abridged, from git 2.56.0
git diff
#> diff --git a/analysis/scripts/01-clean.R b/analysis/scripts/01-clean.R
#> --- a/analysis/scripts/01-clean.R
#> +++ b/analysis/scripts/01-clean.R
#> @@ -1,3 +1,3 @@
#> cohort <- read.csv('analysis/data/raw_data/extract.csv')
#> cohort <- subset(cohort, age >= 18)
#> -sd_cut <- 3
#> +sd_cut <- 2Together the log and the diff answer the two questions the FINAL-file drawer could not. The log tells us when and why a thing changed, and the diff tells us what exactly the change consisted of. To illustrate, consider the commit history of the first weeks of an incident-diabetes cohort study. It is rendered below as it might appear to an auditor reviewing how the reported hazard ratio came to be. The table is generated from synthetic data, so that we may display a realistic history without any real project’s contents.
library(tibble)
library(dplyr)
library(knitr)
commit_history <- tibble::tibble(
hash = c('a1b2c3d', 'e4f5a6b', 'c7d8e9f',
'b0a1c2d', 'd3e4f5a', 'f6a7b8c',
'a9b0c1d'),
date = as.Date(c('2026-02-03', '2026-02-05',
'2026-02-09', '2026-02-12',
'2026-02-18', '2026-02-24',
'2026-03-02')),
author = c('analyst.a', 'analyst.a', 'analyst.a',
'analyst.b', 'analyst.a', 'analyst.b',
'analyst.a'),
message = c(
'Initialize compendium and .gitignore',
'Add cleaning script for registry extract',
'Build analysis-ready cohort table',
'Fit Cox model for 30-day readmission',
'Tighten outlier threshold to 2 SD per reviewer 2',
'Add Kaplan-Meier figure to report',
'Correct person-time denominator'),
files_changed = c(2L, 1L, 3L, 1L, 1L, 2L, 1L)
)
commit_history |>
dplyr::mutate(date = format(date, '%Y-%m-%d')) |>
knitr::kable(
col.names = c('Hash', 'Date', 'Author',
'Message', 'Files'),
align = c('l', 'l', 'l', 'l', 'r'))| Hash | Date | Author | Message | Files |
|---|---|---|---|---|
| a1b2c3d | 2026-02-03 | analyst.a | Initialize compendium and .gitignore | 2 |
| e4f5a6b | 2026-02-05 | analyst.a | Add cleaning script for registry extract | 1 |
| c7d8e9f | 2026-02-09 | analyst.a | Build analysis-ready cohort table | 3 |
| b0a1c2d | 2026-02-12 | analyst.b | Fit Cox model for 30-day readmission | 1 |
| d3e4f5a | 2026-02-18 | analyst.a | Tighten outlier threshold to 2 SD per reviewer 2 | 1 |
| f6a7b8c | 2026-02-24 | analyst.b | Add Kaplan-Meier figure to report | 2 |
| a9b0c1d | 2026-03-02 | analyst.a | Correct person-time denominator | 1 |
Two features of this history could not come from a bare list of files. The fifth commit records that the outlier threshold changed in response to a reviewer. The final commit records a correction to the person-time denominator, the sort of methodological fix whose provenance an auditor will want to establish.
.gitignore and PHIWe come now to the gravest of the three judgments. A commit records the files git is tracking, and by default git offers to track every file in the working tree. Two categories of file must be kept out of that net. The mechanism for keeping them out is the .gitignore file, a plain-text list of path patterns that git will refuse to track.
The first category is the merely unwanted. These are files that can be committed but should not be, because they are regenerable or bulky and would only clutter the history. Rendered outputs (a compiled PDF, an .html report, the figures a script regenerates on every run) are the clearest case. Committing them couples the history to products that the code already determines. Large raw data files bloat every clone. Editor and operating-system cruft (.Rhistory, .DS_Store, .Rproj.user/) is pure noise. None of these is dangerous; all of them are better ignored.
The second category makes this section a matter of ethics and law. It comprises files that must never enter the history, because making them permanent and shareable would be a breach. In health research three kinds dominate.
.Renviron holding a secret, private keys: a credential committed to a repository, and worse pushed to a remote, is a credential to be treated as compromised.Protected health information, identifiable data, and anything held under a data-use agreement that forbids redistribution must never go into a git history. The rule admits no exception: not even briefly on a branch that is never merged, and not even in a local repository that will ever be pushed. A commit is permanent by design and, once pushed, copied to every clone. The gravest and least intuitive fact about git is that its ordinary commands only ever add to the history. Suppose a file containing protected health information is committed, and the mistake is noticed and the file deleted in a later commit. The file is gone from the working tree but remains in full in the history. It is recoverable by anyone with a clone from the commit that introduced it. The deletion is itself just another commit layered on top; it conceals nothing. Removing the file requires rewriting the history. That rewrite changes every subsequent commit hash, cannot reach copies already made, and is error-prone precisely when it matters most. If the offending commit was ever pushed to a remote, one must assume it has been cloned and cached beyond recall. The only sound response is then to treat the exposed data as disclosed and follow the applicable incident procedure. The remedy is therefore prevention. That means a correct .gitignore written before the first commit, and the habit of reading git status before every commit to confirm that nothing sensitive has been staged.
When prevention has failed, the order of the response matters more than the commands, and the commands are the last step.
Stop and report. Push nothing further. If the commit reached any remote, a disclosure has occurred. Notify the data steward, privacy office, or IRB under the institution’s incident procedure, because that obligation is not a technical question and does not wait for the cleanup.
Rotate credentials first. If the file held a password, token, or key, revoke or rotate it at once. A rotated secret is harmless wherever copies survive; a rewritten history is not a substitute (GitHub, n.d.).
Rewrite the history on a fresh clone. git filter-repo removes the file from every commit on every branch and tag. Its --sensitive-data-removal option also fetches all refs first and keeps the remote configured so that the result can be pushed.
git clone https://github.com/lab/diabetes-cohort.git
cd diabetes-cohort
git filter-repo --sensitive-data-removal --invert-paths \
--path analysis/data/raw_data/extract.csv
# expect no output: the file is in no remaining commit
git log --all --oneline -- analysis/data/raw_data/extract.csv
git push --force --mirror originThe force-push may require branch protection to be lifted for the purpose and restored afterwards.
In a repository that holds records under GxP or another regulated quality system, a history rewrite is a controlled change, not a cleanup. Before running it, open a deviation or incident, obtain QA approval under the organization’s SOPs, document what is being removed and why, and keep whatever record of the pre-rewrite state the quality system requires. The audit-trail provision of 21 CFR Part 11 states that ‘Record changes shall not obscure previously recorded information’ (21 CFR Part 11, n.d., Section 11.10(e)). A rewrite obscures that information by design, which is why the deviation record must carry what the history no longer does. Better still, keep regulated records out of a rewritable forge in the first place, so that the question never arises.
Clean what the forge holds. On GitHub the purged commits can remain reachable through cached views and pull-request references, which the owner cannot push over. Removing them requires a request to GitHub Support. Forks are not touched by the rewrite at all, and their owners must be asked to delete them (GitHub, n.d.).
Replace every clone. Every collaborator’s clone still holds the file, and a collaborator who pulls and pushes from an old clone puts it back. Each one must delete the clone and clone afresh, and any copy outside the team’s reach, a backup, a CI cache, a stranger’s clone, is beyond recall (GitHub, n.d.).
In a scratch repository, a clone made before the rewrite still lists the offending commit after the remote has been cleaned; the rewrite reaches only the copies it is run on and pushed to.
A .gitignore is a small file, and its content depends on the archetype of the compendium, a classification the next chapter, Chapter 5, develops in full. For now two archetypes suffice: a data-analysis compendium, whose deliverable is a set of results from data, and an R-package compendium, whose deliverable is reusable code. The reproducibility machinery is identical across archetypes; the list of files to ignore is not. A data-analysis compendium ignores its derived outputs and its raw data. These are the regenerable tables and figures, and the large or sensitive registry extract that must stay out of the history entirely. An R-package compendium has no analysis/ outputs to ignore but must ignore its build artifacts. These are the .Rcheck directory, the built .tar.gz and binary archives, and the src/ object files a compiled package leaves behind. The two .gitignore files barely overlap, and writing the right one is part of naming the archetype.
# .gitignore for a data-analysis compendium
# --- sensitive: never commit ---
analysis/data/raw_data/*
.Renviron
*.pem
# --- regenerable outputs ---
analysis/figures/*
analysis/tables/*
analysis/report/*.pdf
analysis/report/*.html
# --- editor and OS cruft ---
.Rhistory
.RData
.Rproj.user/
.DS_Store# .gitignore for an R-package compendium
# --- build artifacts ---
*.tar.gz
*.Rcheck/
src/*.o
src/*.so
# generated pkgdown site; a comment must be on its own
# line, since text after a pattern is part of the pattern
docs/
# --- editor and OS cruft ---
.Rhistory
.RData
.DS_StoreTwo refinements warrant mention. A leading ! re-includes a pattern otherwise ignored. This is how one ignores a whole data directory but keeps a small, non-sensitive example file or a data dictionary under version control (analysis/data/raw_data/* followed by !analysis/data/raw_data/data_dictionary.csv). Second, a committed-by-accident file, once added to .gitignore, is still tracked until explicitly untracked with git rm --cached. Ignoring a file does not retroactively remove an already-committed copy, which returns us to the warning above.
This book’s own repository applies the rule to its running cohort. The extract analysis/data/raw_data/cohort_raw.csv is synthetic and describes no real person, yet it is not committed. What is committed is the script that writes it, analysis/scripts/simulate_cohort.R, which regenerates the extract from stated parameters; a reader with a fresh clone runs it once before the examples. The .gitignore excludes the whole raw_data directory rather than the one filename, so that a second extract saved there under any name is excluded too. The check below confirms that the generated extract carries identifying-looking fields, that the generator is present, and that the directory pattern is in force.
raw <- load_cohort('../data/raw_data/cohort_raw.csv')
nrow(raw)
#> [1] 338
intersect(c('mrn', 'patient_name', 'dob'), names(raw))
#> [1] "mrn" "patient_name" "dob"
gitignore <- readLines('../../.gitignore')
repo_state <- c(
generator_present = file.exists('../scripts/simulate_cohort.R'),
raw_dir_ignored = 'analysis/data/raw_data/*' %in% gitignore
)
repo_state
#> generator_present raw_dir_ignored
#> TRUE TRUEThe generated extract carries 3 of the three columns this section warns against, by name. The synthetic cohort invents an identifier, a name, and a date of birth so that the risk appears in a real file instead of only in prose. The generator is present, and the pattern analysis/data/raw_data/* is in the .gitignore, which is the arrangement a real project should copy: the code that produces or fetches the extract under version control, the extract itself never.
A .gitignore guards paths, however, and nothing else. The tests in inst/tinytest/ need a copy of the cohort, and an earlier version of this repository met that need by copying the extract to inst/testdata/cohort_raw.csv and committing it. No ignore pattern covered that path, so the identifier columns entered the history by a second route while the first stayed closed. The fixture now at that path is derived from the synthetic extract. It keeps the rows and the duplicate structure the tests need, drops the name and date-of-birth columns, and replaces each record number with a pseudonymous ID-0001-style id.
Replacing the file only added a commit, and the earlier copy is still in the history. Two commands find it. The first lists every commit, on any branch, that touched the path; the second prints the header of the file as the oldest of those commits recorded it.
git log --all --oneline -- inst/testdata/cohort_raw.csv
git show <oldest-hash>:inst/testdata/cohort_raw.csv | head -1#> commits_touching_path old_copy_has_identifiers
#> 2 1
#> old_copy_same_bytes
#> 1
Run on this repository when the page was rendered, the log listed 2 commits touching the path. The oldest, 0bec92e, still holds a copy whose header names patient_name and dob, and its bytes are identical to the generated extract. Anyone holding a clone, made at any time since, can read it. The data are synthetic, so nothing real has leaked, but the pattern is the one by which real data leak: an extract protected at one path and copied, for a convenience such as a test, to another. Removing the copy from the history would take the rewrite described above, with every cost listed there; we keep it as this worked example. Deriving the new fixture from the extract is acceptable here only because the extract is synthetic. Rows of real data with the name columns dropped still carry dates, ages, and measurements that can re-identify, so a fixture for a real project is generated or built from the data dictionary, and a commit that adds a data file under any path warrants the question of where its rows came from.
With the history and its exclusions in place, we turn to its shape. For a solo analyst working linearly, a single line of commits on the main branch is often the whole story, and it is honest to say so rather than to impose ceremony. But two situations make branches worth the small investment of learning them. The first is speculative work: trying an alternative model specification, or a reviewer’s proposed reanalysis, without disturbing the main line that produced the current results. The second is collaboration, treated in the next section. There each contributor works on a branch of their own, and the branches are merged only when ready.
A branch is created and switched to in one command, and merged back with another.
# create and switch to a branch for a reanalysis
git switch -c sensitivity-analysis
# ... make commits on the branch ...
# return to main and merge the branch in
git switch main
git merge sensitivity-analysisThe mental model is the one given above: a branch is a movable name for a line of development, and main is merely the name given to the first branch, here by git init -b main. Nothing about branching changes the commit model; it only lets two lines of commits coexist and later rejoin. We keep the treatment light here. We shall return to the collaborative use of branches, which is where they earn their keep, when we reach pull requests.
Figure 4.2 draws the shape. The branch does not copy the history. It names a new commit whose parent is a commit on main, and the merge names a commit with two parents. Everything before the branch point is shared, and no hash anywhere in the diagram changes when the branch is created or merged.
library(ggplot2)
library(tibble)
nodes <- tibble(
id = c('A', 'B', 'C', 'M', 'D', 'S1', 'S2'),
x = c(1, 2, 3, 4.6, 5.7, 3.1, 4.0),
y = c(0, 0, 0, 0, 0, 0.8, 0.8),
shade = c(rep('main', 5), 'branch', 'branch')
)
edges <- tibble(
x = c(1, 2, 3, 4.6, 2, 3.1, 4.0),
xend = c(2, 3, 4.6, 5.7, 3.1, 4.0, 4.6),
y = c(0, 0, 0, 0, 0, 0.8, 0.8),
yend = c(0, 0, 0, 0, 0.8, 0.8, 0)
)
ggplot() +
geom_segment(data = edges,
aes(x = x, y = y, xend = xend, yend = yend),
color = 'grey45', linewidth = 0.45) +
geom_point(data = nodes, aes(x = x, y = y, fill = shade),
shape = 21, size = 9, stroke = 0.5,
color = 'grey30', show.legend = FALSE) +
geom_text(data = nodes, aes(x = x, y = y, label = id),
size = 3, fontface = 'bold') +
scale_fill_manual(values = c(main = '#c3ddda',
branch = '#f0e2c4')) +
annotate('text', x = 0.55, y = 0, label = 'main',
hjust = 1, fontface = 'bold', size = 3.2) +
annotate('text', x = 2.55, y = 0.8, label = 'branch',
hjust = 1, fontface = 'bold', size = 3.2) +
annotate('text', x = 4.6, y = -0.52,
label = 'M: two parents', size = 2.9,
color = 'grey25') +
annotate('text', x = 2.0, y = -0.52,
label = 'branch point', size = 2.9,
color = 'grey25') +
coord_cartesian(xlim = c(-0.1, 6.1), ylim = c(-0.8, 1.1)) +
theme_void()
main; the upper line is a sensitivity-analysis branch created at commit B and merged back at M. Commits A through C exist once and are shared by both lines: the branch adds commits rather than copying them. The merge commit M is the only commit in the diagram with two parents, which is what records that the two lines rejoined and when.
Two kinds of trouble are common enough to deserve their own section: a change that needs to be undone, and a merge that git cannot finish by itself.
Undoing. Git has three distinct commands for undoing work, and the right one depends on where the unwanted change lives.
git restore <file> discards unstaged edits in the working tree, putting the file back to its last committed (or staged) content. It never touches history; there is no commit to undo, only a draft to throw away.
# an edit no one has staged or committed
echo 'threshold <- 99' > analysis.R
git restore analysis.R
# analysis.R is back to its last committed contentgit reset moves what HEAD points to. That is, it moves the branch itself to an earlier (or different) commit. The three flags differ only in how much else they touch along the way:
--soft moves HEAD and leaves everything else alone: the undone commit’s changes reappear staged, ready to be recommitted differently.--mixed, the default, additionally unstages those changes, so they sit in the working tree, edited but not staged.--hard additionally overwrites the working tree, discarding the changes outright.# move HEAD back one commit; --mixed is the default
git reset HEAD~1
# the undone commit's edits are now unstaged, not gone
git reset --hard HEAD~1
# the undone commit's edits are discarded entirelyA reset, like the amend and rebase discussed earlier in this chapter, is a rewrite of what the branch name points to, not an addition to history. The same caution applies. A reset is harmless on commits that exist only in the analyst’s own clone. It is a serious act, needing the collaborators’ agreement and a force-push, once those commits have been pushed or pulled elsewhere. A local reset that moves past commits can usually be undone. The discarded commits are not immediately deleted, and git reflog lists where HEAD pointed before the reset, so git reset --hard <that-hash> restores them. The reflog records only commits, however. Edits that were never committed are not in it, and --hard overwrites them in the working tree. Unstaged edits are then gone permanently; staged ones survive only as unnamed objects that git fsck --lost-found can sometimes recover, file by file and without their names. Before any --hard, therefore, read git status, and commit or git stash whatever uncommitted work should survive.
git revert <commit> takes the opposite approach. Instead of moving HEAD backward, it makes a new commit whose changes are the exact opposite of the one named, applied on top of the current history. The reverted commit is left untouched, in place, for anyone to read later. Because revert only ever adds a commit, it is the one of the three that is safe on a branch other people have already pulled; reset and amend are not.
git revert HEAD
# creates a new commit, e.g. "Revert 'Add note line'",
# that undoes the previous commit's changes; the
# reverted commit itself still exists in the historyThe choice can be stated briefly. For an edit that is not yet staged, use restore. For a commit that exists only on a private branch, reset is simplest. For a commit that others may already have, use revert and let history show both the mistake and its correction.
Merge conflicts. A merge like the one in Figure 4.2 goes through cleanly whenever the two branches changed different lines. When both branches change the same lines of the same file, git has no way to choose between them, and the merge stops partway, leaving the decision to the analyst.
git switch main
git merge sensitivity-analysis
# Auto-merging analysis.R
# CONFLICT (content): Merge conflict in analysis.R
# Automatic merge failed; fix conflicts and then
# commit the result.git status reports the file as having ‘unmerged paths’, and the file itself now contains both versions, separated by conflict markers that git inserts directly into the text:
<<<<<<< HEAD
threshold <- 4
=======
threshold <- 5
>>>>>>> sensitivity-analysis
Everything between <<<<<<< HEAD and the ======= divider is the current branch’s version; everything between the divider and the final marker is the version being merged in. Resolving the conflict means editing the file by hand down to the single version that should survive. That may be one side, the other, or a combination of both. The analyst then deletes the markers themselves; nothing removes them automatically. Once the file reads the way it should, the usual two-step cycle finishes the merge. One runs git add on the resolved file to tell git the conflict is settled, then git commit to record the merge. (git merge --abort backs out of the whole attempt instead, if the conflict turns out to need more thought than a mid-merge edit allows.)
# edit analysis.R to resolve the conflict, then:
git add analysis.R
git commit -m "Merge sensitivity-analysis: keep threshold 4"A conflict is not git malfunctioning; it is git correctly refusing to guess at a scientific decision, such as which of two threshold values the analysis should use, that only the analyst can make.
Everything so far is local. The repository, its history, and its branches all live in the .git directory on one machine, and if that machine is lost, so is the work. A remote is a copy of the repository hosted elsewhere, on GitHub, on GitLab, or on an institution’s own server. Connecting a local repository to a remote serves three distinct purposes that are worth separating.
The first is backup. A remote holds a complete copy of the history, so that a lost laptop costs at most the commits made since the last push. The second is distribution. A public remote is the mechanism by which a compendium becomes locatable to the world. It is a URL a reviewer can be given, a repository a reader can clone, the concrete form of the L0 rung of the ladder. The third is collaboration, the purpose that shapes the rest of this section.
The commands that connect to and synchronize with a remote are few. One names the remote once, then pushes local commits to it and pulls others’ commits from it.
# connect the local repo to a remote named origin
git remote add origin https://github.com/lab/diabetes-cohort.git
# push the main branch and remember the link
git push -u origin main
# later: send new local commits up
git push
# and bring collaborators' commits down
git pullConsider a team working across sites, a clinical trial with several participating centers, a multi-institution consortium. Such a team works in one of two models on GitHub and GitLab. In the shared-repository model, every contributor has write access to one repository, works on a branch of it, and the main branch is protected so that nothing reaches it without review. This is the usual arrangement for a private trial repository, where forking is often disabled. In the fork-and-pull-request model, a contributor without write access forks the canonical repository, making a personal copy on the remote, and works on a branch of that fork. In either model the contributor opens a pull request (GitLab calls it a merge request, the same thing under another name) proposing that the branch be merged into main. The pull request is a unit of review. The maintainers see exactly the diff being proposed, discuss it inline, request changes, and merge it only when satisfied. In a multi-site analysis, the pull request is a documented, attributable, reviewable gate through which every change to the shared analysis passes. Its record, who proposed what, who reviewed it, what was said, and when it was merged, is held on the forge’s servers rather than asserted by a client. It therefore complements the commit history with a record of the review of each change that is harder to backdate. That record is review evidence, not by itself a regulated signature. An approval on a forge does not, by default, carry the printed name, the date and time, and the meaning of the signature that 21 CFR 11.50(a) requires of a signed electronic record (21 CFR Part 11, n.d.). Whether it counts as a controlled approval depends on the organization’s validated configuration of the forge and on its SOPs.
The same gate serves when the contributor is a coding agent. The agent works on a branch of its own and opens a pull request; the analyst reads the diff, reviews it, and alone decides whether to merge. The agent’s account of its change is a description to check against the diff, not a substitute for reading it (Section 2.10.1).
The last piece of the remote’s vocabulary is the pair tags and releases, and they matter to reproducibility specifically. A tag is a permanent, human-readable name for one commit. git tag -a v1.0-submission -m "State at journal submission" marks, forever and unambiguously, the exact state of the analysis at the moment a manuscript was submitted. A release on GitHub or GitLab is a tag dressed with notes and downloadable archives. The reproducibility payoff is that a reviewer, or the analyst a year later, can recover the precise state that produced the submitted numbers by naming the tag. There is no need to guess which commit was current on the submission date. In Chapter 13 we shall see the same tagged state deposited to a public archive with a citable identifier. The tag is the local anchor to which that archival identity attaches.
Having made version control the foundation, we must be exact about the boundary of what it provides. The whole discipline of this book is matching a claim to what has actually been secured. Git versions text and tracks its history. It records every state of the files under it and the reason each committer gave for each change. That is the entirety of what it does, and it is the L0 rung of the ladder. An analysis under version control is locatable, findable and readable by a second person, and no more.
In particular, git does not pin the package versions an analysis uses. A repository cloned a year later contains the same analysis.R, but running it installs whatever package versions are current. These may not be the versions the analyst used, so the code that ran may no longer run, or may run and return a different number. Git also does not pin the computational environment. The R version, the operating system, the system libraries a package links against are nowhere in the history, and a clone is at the mercy of whatever the next machine provides. These are exactly the layers of the determinant stack that Chapter 3 enumerated as unpinned at L0. Closing them is the work of the two chapters that follow. The lockfile of Chapter 6 pins the package layer to reach L1, and the container of Chapter 7 pins the environment layer to reach L2. Version control is necessary for all of this, since the lockfile and the Dockerfile are themselves files whose history git tracks. It is sufficient for none of it.
This chapter’s own practice reaches L0, locatable, by placing the repository under version control and pushing it to a remote. The cohort extract is not part of that history; its generator is, and the extract is regenerated from it. The practice leaves every layer beneath the analysis code, the packages, the environment, and the rest of the determinant stack, exposed and unpinned.
To make the chapter concrete, we take the incident-diabetes cohort of the running example from an untracked folder to a tagged, remotely hosted repository. We stay at the level of the commands and the judgment behind them. The shell sessions below are not executed when the book renders. The outputs shown with #> were captured once, on 2026-11-08, from a scratch copy of the example with a synthetic identity, and are abridged.
The analyst begins with a folder of scripts and a registry extract. The very first act, before a single commit, is to write the .gitignore, because the extract contains protected health information that must never enter the history.
cd diabetes-cohort
git init -b main
# write .gitignore FIRST, ignoring raw_data and credentials
git status --untracked-files=all # is the extract listed?The flag matters. Plain git status collapses a directory that holds no tracked files into one line, here analysis/, so it cannot show whether the extract inside is ignored. Run on a scratch copy of this example, the full listing names the extract before the .gitignore is written and omits it after, and git check-ignore -v names the rule responsible.
# output abridged, from git 2.56.0
# before .gitignore
git status --untracked-files=all
#> Untracked files:
#> DESCRIPTION
#> analysis/data/raw_data/extract.csv
#> analysis/scripts/01-clean.R
# after .gitignore
git status --untracked-files=all
#> Untracked files:
#> .gitignore
#> DESCRIPTION
#> analysis/scripts/01-clean.R
git check-ignore -v analysis/data/raw_data/extract.csv
#> .gitignore:1:analysis/data/raw_data/ analysis/data/raw_data/extract.csvOnly once git status confirms that the sensitive extract is ignored does the analyst make the first commit, the one that lifts the folder to L0, locatable. Its output names the branch, marks the commit as the root of the history, and lists the files it records.
git add .gitignore DESCRIPTION
git commit -m "Initialize compendium and .gitignore"
# output abridged, from git 2.56.0
#> [main (root-commit) 936e050] Initialize compendium and .gitignore
#> 2 files changed, 4 insertions(+)
#> create mode 100644 .gitignore
#> create mode 100644 DESCRIPTIONA commit that stops instead with ‘Please tell me who you are’ means git has no identity on this machine. The Git preflight sets it, and When git refuses lists this and the other refusals a first push can meet.
Work proceeds as a sequence of small, message-bearing commits: the cleaning script, the derived cohort table, the Cox model. Each is its own commit with its own reason, exactly the history tabulated in Table 4.1. When a reviewer later asks why the outlier threshold changed, the answer is one git log away.
To try a reviewer’s proposed reanalysis without disturbing the results already reported, the analyst branches.
git switch -c reviewer-sensitivity
# ... reanalysis commits ...
git switch main # main is untouched and still runsThe work is backed up and made locatable by connecting a remote and pushing.
git remote add origin https://github.com/lab/diabetes-cohort.git
git push -u origin main
# output abridged, from git 2.56.0 (local stand-in remote)
#> * [new branch] main -> main
#> branch 'main' set up to track 'origin/main'.
git status
#> On branch main
#> Your branch is up to date with 'origin/main'.The last line of the push is the one to look for: the local main now tracks the remote’s, so a later bare git push or git pull knows where to go. The scratch run pushed to a local bare repository rather than to a forge, so its output omits the forge’s own progress lines. A push that is refused instead is diagnosed from When git refuses.
A collaborator at a second site forks the repository, adds a site-specific adjustment on a branch of their fork, and opens a pull request. The analyst reviews the diff inline, requests one change, and merges it, leaving a reviewable record of the exchange. Finally, at journal submission, the analyst marks the exact state.
git tag -a v1.0-submission -m "State at journal submission"
git push origin v1.0-submissionThe folder is now a version-controlled, remotely hosted, tagged repository. It is firmly at L0, with a clean history, a reviewed collaboration record, and a permanent anchor to the submitted state. It is not yet L1 or L2, because nothing has pinned the packages or the environment, and the honest reproducibility statement says exactly that. The lockfile of Chapter 6 is the next commit.
A language model is a fluent assistant for git, which is a domain rich in memorized command recipes. Precisely that fluency is the hazard. Check every command it proposes for operations beyond what was asked, irreversible ones above all; the model does not know which of the analyst’s files are sensitive. A coding agent that works in the repository can read those files, run git itself, and push. It is therefore run only in projects whose data it is allowed to see, and never with credentials that let it push to a remote unreviewed.
One rule comes first (habit 3). Never paste or upload protected health information, identifiable records, or data held under a data use agreement, nor outputs derived from them, into a model or a coding agent unless three conditions all hold. The institution has approved that endpoint for that class of data. The IRB protocol and the consent permit the processing. The data use agreement, or the provider’s terms, permits it. If any of the three is unclear, the answer is no.
The third condition is the one most often missed. Institutional approval of a tool does not override the terms under which a data provider released the data. NIH, for example, treats sharing controlled-access data through prompts with public generative AI tools, which it glosses as third-party tools, as a breach of the data use certification. It treats a model trained on such data as a data derivative, to be shared only with other approved users and not kept after the project closes (National Institutes of Health, 2025).
Describe the structure instead: the column names and types, or a small synthetic example generated from the data dictionary, never edited from real rows. A coding agent sees whatever files are in its working tree, so run it in a checkout or container where the real data is not mounted.
An agent also acts, so confine it to a branch and keep merges, pushes, and deposits for yourself (Section 2.10.1).
For git, the structure a prompt describes is the repository’s: its paths and file types, not the contents of the files. The three triples below mark the division of labor.
Prompt. ‘I accidentally committed a file of patient data three commits ago. Give me the git commands to remove it.’
Watch for. A history-rewriting recipe (git filter-repo, or the older filter-branch, or a reset) presented as a clean fix. The model cannot know whether the offending commit was ever pushed to a remote. That is the fact that determines whether removal is even possible, so check whether the answer raises the breach question at all.
Verification. Treat the exposure, not the git command, as the primary problem. Establish first whether the commit was pushed. If it was, assume the data has been cloned and cached and follow your institution’s incident procedure, because no git command can recall it. Only then apply a rewriting tool, on a fresh clone and in the order the five-step procedure earlier in this chapter gives, and in a repository of regulated records only as the approved, documented change its third step requires. Check that the recipe covers the forge’s caches, forks, and every collaborator’s clone. A coding agent asked the same question does not stop at a recipe: it can run the rewrite and the force-push itself. The breach assessment, the decision to rewrite, and the force-push stay with the analyst. At most the agent prepares the commands on a fresh clone, for the analyst to read and run (Section 2.10.1).
Prompt. ‘Write a .gitignore for my R health-data analysis project.’
Watch for. A generic R .gitignore (the standard .Rhistory, .RData, .Rproj.user/ list) that omits the one category that matters most, the raw data and credentials specific to your own project. A chat model has not seen your directory. A coding agent may have listed it, but a file’s name does not say whether it holds PHI. An agent that opened the files to find out has already read the data, which is why it belongs only in projects it is cleared to see.
Verification. Take the generic list as a starting point, then add, by hand, the explicit paths of every raw-data directory, every .Renviron or credential file, and every restricted dataset. Confirm with git status that each is untracked before the first commit. The generic patterns are safe to accept; the project-specific sensitive paths are yours to supply.
A better prompt. ‘Below is the directory tree of my R analysis compendium, file names only, with no file opened. Write a .gitignore that excludes analysis/data/raw_data/, .Renviron and any other credential file, and regenerable outputs, but keeps the code, renv.lock, and the synthetic cohort tracked. Label each line generic or project-specific, and list the commands that would show me each sensitive path is ignored.’
Prompt. ‘Write good commit messages for these changes.’
Watch for. Messages that fluently describe what changed, which the model can read from the diff, but invent or omit the why. The why is the scientifically load-bearing part, and the model cannot know it. A plausible-sounding ‘Update outlier threshold’ hides the reviewer request that the record must carry.
Verification. Supply the reason yourself. Let the model draft the imperative summary line from the diff, then edit in the motivation, the reviewer comment, the corrected denominator, the protocol amendment, that turns a description into an accountable record.
Take a folder of your own currently versioned by the FINAL-file method, count the manual snapshot files it contains, and for two of them state what changed between them and why. Note which of those two questions you can still answer, and use the difficulty as a measure of what a commit history would have preserved.
Initialize a git repository in a scratch directory, make three commits that each change one file, and then use git log --oneline and git show to recover, for the middle commit, both what changed and the message you wrote. Confirm that the commit hashes are unchanged by a later commit.
Write a .gitignore for a data-analysis compendium and a second for an R-package compendium, and list the patterns that appear in one but not the other. Explain each difference in terms of what the archetype produces.
Explain, to a colleague who has just deleted a PHI-containing file in a new commit and believes the problem solved, why the file is still in the history, what determines whether it can be removed, and what to do if the offending commit was already pushed to GitHub.
Construct the sequence of commands by which a collaborator at a second trial site would contribute a change through a fork and a pull request, and state, for each step, what part of the project’s record it adds that a direct push to main would not.
An analyst pushes a version-controlled compendium to GitHub and writes in the methods section that the analysis is ‘fully reproducible’. State the rung the analysis has actually reached, name the two layers of the determinant stack that remain unpinned, and rewrite the sentence so that it claims exactly what version control secures and no more.
In a fresh clone of this book’s repository, run Rscript analysis/scripts/simulate_cohort.R from the top directory, then raw <- load_cohort('analysis/data/raw_data/cohort_raw.csv'). Report nrow(raw) and the three columns among names(raw) that would, in a real project, require the extract to sit behind the .gitignore pattern analysis/data/raw_data/*, and use git check-ignore -v analysis/data/raw_data/cohort_raw.csv to name the line that excludes it. Then run git log --all --oneline -- inst/testdata/cohort_raw.csv and state what the oldest commit it lists shows about whether that pattern kept the identifier columns out of the history.
This exercise returns to the determinant stack and the L0-to-L3 ladder of Chapter 3 (Chapter 3). A colleague deletes the .git directory of a well-tested, fully containerized analysis and runs git init again to ‘start clean’ before pushing, so the repository now hosted on GitHub shows a single commit from yesterday. Using what this chapter and Chapter 3 together establish, state the rung the repository occupies today, and explain what the colleague’s own prior discipline, the lockfile and the container, can and cannot restore of what the deleted history held.
Attempt an exercise before expanding its solution. The first two ask you to work in your own directories, so what you produce will vary; the boxes say what a good answer establishes.
| Command or rule | What it does |
|---|---|
git init -b main |
Starts tracking the current directory as a repository, with the first branch named main. |
git add <file> |
Stages a change for the next commit. |
git commit -m '...' |
Records the staged changes with a message. |
git status |
Shows staged, unstaged, and untracked files; read it before every commit (habit 3). |
git log --oneline |
Lists commits, most recent first, by hash and message. |
git show <hash> |
Displays one commit’s full diff. |
git switch -c <name> |
Creates and switches to a new branch. |
git remote add origin <url>; git push -u origin main
|
Connects to, and first pushes to, a remote. |
git tag -a v1.0 -m '...' |
Marks one commit permanently, e.g. at submission (Chapter 13 anchors to this). |
!pattern in .gitignore
|
Re-includes a path otherwise ignored, e.g. a data dictionary beside an ignored extract. |
git check-ignore -v <path> |
Names the .gitignore rule that ignores a path, or prints nothing if none does. |
git rm --cached <file> |
Untracks a file already committed; does not erase it from the history. |
| Git refuses | Look up the message in When git refuses; run the Git preflight once per machine. |
git filter-repo --sensitive-data-removal |
Rewrites every commit to remove a file; only on a fresh clone, only before re-pushing. Where records are regulated, only as an approved, documented controlled change. |
| Rule of thumb | PHI, credentials, and restricted data are never committed; deleting them later does not remove them from the history. |
| Rule of thumb | Version control reaches L0 only; it pins the analysis code, not the packages or the environment. |
| Habit 1 | Commit before you compute. |