# Version Control in Shared Lab Notebooks By the end of this guide you will be able to set up version control for a shared [lab notebook](/knowledge/molecular-biology/lab-notebook), save every change as an attributed, time-stamped commit, recover yesterday's protocol after a bad edit, resolve a conflict when two lab mates change the same line, and decide whether an electronic lab notebook, a Git repository, or both belong in your lab. You need a computer with Git installed, a folder or hosting space the whole group can reach, and about an hour. Version control in shared lab notebooks solves a problem every wet lab and computational lab knows well. Five people, one notebook, and a hundred small edits produce a record nobody can fully trust. Modern life science experiments generate large data sets and demand high levels of data integrity, conditions that paper notebooks handle poorly and that electronic systems were designed to address [1]. This guide covers the concepts, compares the main options, and walks through the commands you can run today. ## What Version Control Means in a Lab Notebook Version control is any system that records every saved change to a set of files, along with who made the change, when, and why, so any earlier state can be restored later. In a lab notebook setting that covers protocols, daily observations, sample inventories, and analysis scripts. A few terms recur throughout this article: - A **repository** is the folder version control watches, plus the hidden database that stores its history. - A **commit** is one saved snapshot of the repository. Each commit carries a unique identifier called a **hash**, an author, a date, and a message you write. - A **revision history** is the ordered list of saved versions. Electronic lab notebooks usually show this as page history. - An **audit trail** is a secure, system-generated record of who changed what and when. - An **electronic lab notebook (ELN)** is software for recording experiments digitally. A **paper lab notebook (PLN)** is the bound book it replaces. Life science experiments increasingly produce large data sets and require high levels of data integrity, and ELNs are better equipped than PLNs to meet those demands [1]. The design of early online ELNs points to a feature set that separates a real shared notebook from a word processor sitting in a shared folder. The eCAT platform, one of the first online ELNs, was built around a permissions system, controlled sharing, an audit trail, electronic signature, and search, with an interface intended to feel like the electronic counterpart of a paper notebook [2]. Every one of those features depends on version control underneath. Permissions decide who may change a record, the audit trail remembers every change, and search only stays useful when the history is complete. ## Why Shared Lab Notebooks Need Version Control Shared notebooks fail in predictable ways. A protocol file accumulates names like `protocol_final.docx`, `protocol_final_v2.docx`, and `protocol_FINAL_really.docx`. Someone overwrites a colleague's edits without noticing. A figure in a manuscript can no longer be traced back to the exact protocol text and raw data that produced it. When a rotation student leaves, their undocumented choices leave with them. Version control addresses each failure directly. Every change is attributed to a person and a moment in time. Nothing is ever silently overwritten, because the previous version remains retrievable. The chain from raw data to final figure, called provenance, stays intact and inspectable. These are also the habits that good documentation practices (GDPs) are meant to enforce. GDPs are the record-keeping behaviors that keep entries attributable, legible, contemporaneous, original, and accurate. A bioprocess engineering teaching lab that adopted the cloud-based ELN LabArchives used it specifically to train students in electronic record keeping, GDPs, and data integrity, and reported that the platform strengthened all three [1]. Shared labs benefit even more than solo researchers, because turnover is constant and the notebook is the only thing that stays. ## Electronic Lab Notebook Comparison: Where Version Control Should Live The practical options fall into four groups: paper notebooks, shared drives with manual copies, cloud-based ELNs, and general version control tools such as Git pressed into notebook service. A cloud-based ELN stores records on the vendor's servers and shows every authorized lab mate the same current version from anywhere. A bioprocess engineering teaching lab that deployed LabArchives reported streamlined workflows, faster data recording and archiving, enhanced sharing and collaboration, and real-time and remote monitoring of experiments [1]. Locally hosted ELNs run on institutional servers and appeal where data cannot leave the building. Git handles text and code superbly but needs discipline around binary files such as images and spreadsheets. Whatever platform you evaluate, judge it against the checklist that shaped early online ELNs: a permissions system, controlled sharing, an audit trail, electronic signature, and search [2]. If a product cannot tell you who changed a record, when, and cannot restore the earlier version, it does not provide version control regardless of the marketing. Adoption, not features, is the usual bottleneck. Limited training and a shortage of people comfortable with electronic record keeping have kept many academic labs on paper, and in the LabArchives teaching lab the attributes tied to positive user experience improved between the first and second year the course ran as training matured [1]. Budget a semester for the transition, not a week. | Option | How versions are captured | Strengths | Watch out for | |, - |, - |, - |, - | | Paper notebook, dated and signed pages | Handwritten entries, taped-in printouts | Familiar, widely accepted for regulated records, no login required | No search or backup, one physical copy, poor fit for large data sets [1] | | Shared drive with manual copies | Files renamed v1, v2, final, final2 | Zero setup cost | Silent overwrites, no attribution, ambiguous latest version | | Cloud-based ELN with page history | Automatic revision history per entry | Sharing, search, remote access, audit trail, electronic signature [2] | Requires training and reliable connectivity, export habits matter [1] | | Git repository beside the ELN | Commits with hash, author, and message | Precise change tracking for protocols and code, works offline | Learning curve, weak with large binary files | ## Lab Notebook Version Control Step by Step If your lab uses a cloud ELN such as LabArchives, the same logic applies inside the platform: keep one entry per experiment, save often, rely on the page revision history, and export a snapshot at each milestone [1]. The Git walkthrough below covers the files that live beside the notebook, which is where most version control accidents happen. ### Step 1. Install Git and identify yourself Install Git from your operating system's package manager or the official Git project website, then confirm the install: ``` git --version ``` Expected output: ``` git version 2.43.0 ``` Create the repository and tell Git who you are. Git writes your name and email into every commit, which is what makes the record attributable: ``` mkdir protein-assay-notebook cd protein-assay-notebook git init ``` Expected output: ``` Initialized empty Git repository in /home/jlee/protein-assay-notebook/.git/ ``` ``` git config user.name "Jane Lee" git config user.email "jlee@university.edu" ``` Run these two commands inside the notebook folder so the identity applies to this repository. If you skip them, your first commit stops with a message that reads `Author identity unknown` followed by `*** Please tell me who you are`. ### Step 2. Describe the notebook and set its boundaries Create a `README.md` that states the notebook's purpose, and a `.gitignore` file that lists what Git should never track: ``` # Protein Assay Notebook Shared notebook for the Lee lab, project PA-2026-03. One markdown file per experiment day. Raw instrument exports live in raw/ and are not tracked. ``` ``` # Large raw exports stay on the shared drive raw/ *.zip # Office lock files ~$* # Operating system clutter .DS_Store Thumbs.db ``` Each `.gitignore` line is a pattern. `raw/` ignores that folder, `*.zip` ignores any zip archive, and `~$*` ignores the lock files that Word and Excel create while a document is open. ### Step 3. Make the first commit ``` git add README.md .gitignore git commit -m "Start shared notebook for project PA-2026-03" ``` Expected output: ``` [main (root-commit) 3f9c1a2] Start shared notebook for project PA-2026-03 2 files changed, 9 insertions(+) create mode 100644 .gitignore create mode 100644 README.md ``` The `-m` flag supplies the message. `main` is the branch name, the default line of history. `3f9c1a2` is the short form of the commit hash, the permanent ID you will use to refer to this snapshot. `root-commit` marks the very first commit in the repository. ### Step 4. Run the daily loop Create one file per experiment day, for example `2026-11-11_BCA-assay_JL.md`. Check what Git sees: ``` git status ``` Expected output: ``` On branch main Untracked files: (use "git add ..." to include in what will be committed) 2026-11-11_BCA-assay_JL.md nothing added to commit but untracked files present (use "git add" to track) ``` Save the new file into history: ``` git add 2026-11-11_BCA-assay_JL.md git commit -m "Add BCA assay run 1, standards prepared per lot 47821" ``` Before committing later edits, review them with `git diff`, which prints pending changes line by line. Deleted lines begin with a minus sign and added lines begin with a plus sign: ``` - Incubate 30 min at room temperature. + Incubate 30 min at 37 C. ``` That minus-plus view is the heart of version control. Anyone can see exactly what changed, not merely that something changed. ### Step 5. Branch before changing a shared protocol A branch is a parallel line of history. Use one whenever you are about to alter a protocol that others depend on: ``` git switch -c incubation-test ``` The `-c` flag creates the branch and moves you onto it in one step. Edit the protocol, commit, then return to the main line: ``` git add protocols/BCA-v2.md git commit -m "Test 45 min incubation on plate reader 2" git switch main ``` ### Step 6. Merge, and resolve conflicts when they appear ![Flowchart showing a merge attempt, a conflict on the same protocol lines, a decision on which value the run data supports, and a committed resolution.](/article-images/illustrations/lab-notebook-version-control-conflict-resolution.webp) Bring the tested change back into the main line: ``` git merge incubation-test ``` Expected output when there are no competing edits: ``` Updating 3f9c1a2..8d1e5f7 Fast-forward protocols/BCA-v2.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) ``` If a teammate edited the same lines on `main` in the meantime, Git refuses to guess: ``` Auto-merging protocols/BCA-v2.md CONFLICT (content): Merge conflict in protocols/BCA-v2.md Automatic merge failed, fix conflicts and then commit the result. ``` Open the file and you will find both versions separated by conflict markers: ``` <<<<<<< HEAD Incubate 30 min at 37 C. ======= Incubate 45 min at 37 C. >>>>>>> incubation-test ``` Decide which line the data supports, delete the markers and the losing line, then finish: ``` git add protocols/BCA-v2.md git commit -m "Merge incubation test, keep 30 min per run 3 data" ``` A merge conflict is version control working correctly. It forces a conversation that a shared drive would have settled silently and wrongly. ### Step 7. Read the history ``` git log ``` Expected output: ``` commit 8d1e5f7a2b9c4d0e1f2a3b4c5d6e7f8a9b0c1d2e Author: Jane Lee Date: Wed Nov 11 16:41:03 2026 -0500 Add BCA assay run 1, standards prepared per lot 47821 commit 3f9c1a2b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f Author: Jane Lee Date: Wed Nov 11 09:02:11 2026 -0500 Start shared notebook for project PA-2026-03 ``` To inspect one commit in full, run `git show 8d1e5f7`. Git prints the message followed by every line that changed, again marked with minus and plus signs. ### Step 8. Undo without destroying history To discard uncommitted edits to a file and return it to the last commit: ``` git restore 2026-11-11_BCA-assay_JL.md ``` To undo a commit that is already saved, create a new commit that reverses it: ``` git revert HEAD ``` Expected output: ``` [main 4e7f9a1] Revert "Change incubation to 45 min" 1 file changed, 1 insertion(+), 1 deletion(-) ``` `HEAD` is a nickname for the most recent commit. Revert is the safe choice in a shared lab because the mistake and its correction both remain in the history, which is exactly what an audit trail requires. ### Step 9. Put the notebook where the lab can reach it Create an empty repository on your institution's Git server or a hosting service such as GitHub, then connect your local folder and upload: ``` git remote add origin https://github.com/lee-lab/protein-assay-notebook.git git push -u origin main ``` Expected output: ``` To https://github.com/lee-lab/protein-assay-notebook.git * [new branch] main -> main branch 'main' set up to track 'origin/main'. ``` Teammates get their own copy with `git clone https://github.com/lee-lab/protein-assay-notebook.git`. From then on the rhythm is simple: `git pull` when you sit down, commit through the day, `git push` before you leave. ## Common Git Errors and Their Fixes - `fatal: not a git repository (or any of the parent directories): .git` appears when you run a Git command outside the notebook folder. Move into the folder with `cd`, or run `git init` if the folder is genuinely new. - `nothing to commit, working tree clean` means Git sees no staged changes. Either you already committed or you forgot `git add`. Run `git status` to see which. - `error: Your local changes to the following files would be overwritten by merge:` followed by `Please commit your changes or stash them before you merge.` appears when you try to merge with unsaved work. Commit your work first, or park it with `git stash` and bring it back afterward with `git stash pop`. - `fatal: pathspec 'protcols/BCA-v2.md' did not match any files` means a typo in a file name. Check the spelling with `ls` or `git status`. - `! [rejected] main -> main (fetch first)` during a push means a teammate uploaded first. Run `git pull`, resolve anything Git reports, then push again. ## A Lab Notebook Template That Plays Well With Version Control File names are your first layer of version control. Use ISO dates, zero-padded run numbers, and initials so listings sort chronologically and every file points to a person: ``` 2026-11-11_BCA-assay_run02_JL.md ``` Read that back as the date first, the assay second, the run third, the operator last. Nobody has to open the file to know what it holds. Inside each entry, capture the fields that make the record trustworthy. The following lab notebook template encodes the documentation habits that the LabArchives teaching deployment used to train students in GDPs and data integrity [1]: ``` # 2026-11-11 BCA protein assay, run 02 (project PA-2026-03) - Operator: J. Lee - Protocol: protocols/BCA-v2.md at commit 8d1e5f7 - Reagents: BCA reagent lot 47821, BSA standard lot 118C - Instrument: plate reader, serial 8842, 96-well plate - Raw data: shared drive, folder PA-2026-03/run02 - Deviations: none - Observations: standard curve r-squared 0.998, unknowns within range - Sign-off: J. Lee, 2026-11-11 16:40 ``` Two lines deserve attention. The protocol line pins the exact commit hash of the protocol you followed, which ties the entry to an immutable version of the method. The sign-off line records human approval, which commits alone do not supply. Pair the template with a commit message convention: present tense, what changed, why. Three examples: ``` Add BCA run 02 entry, standard curve passed Change incubation to 30 min at 37 C per optimization run 3 Fix buffer recipe typo, 10 mM not 100 mM Tris ``` ## Lab Notebook Version Control Tips for Shared Labs 1. **Commit small and often.** One commit per finished unit of work, such as a completed entry or a corrected protocol step, keeps every rollback point meaningful. 2. **Pull before you start, push before you leave.** This two-command habit prevents most conflicts in shared repositories. 3. **Keep one topic per commit.** Mixing a protocol edit with a data upload makes both harder to find later. 4. **Write searchable messages.** Include sample IDs, lot numbers, and run numbers so `git log` doubles as an index. 5. **Tag milestones.** Run `git tag bca-v2-approved` at a frozen protocol, and the tag becomes a permanent bookmark you can pass to `git show`. 6. **Protect the main branch.** Most hosting services let you restrict who can commit to `main` directly, which stops accidental overwrites of the shared record. 7. **Keep bulky raw data out of Git.** Note its location in the entry, and fingerprint archived exports with a checksum so silent corruption gets caught. A checksum is a short digest computed from a file's contents, where any change to the file changes the digest: ``` sha256sum PA-2026-03_run02_raw.csv ``` ``` 9f86d081884c7d659a2feaa0c55ad015 PA-2026-03_run02_raw.csv ``` 8. **Cross-reference the ELN and the repository.** The notebook entry cites the commit hash, and the commit message cites the entry date, so the two records always point at each other. 9. **Train every new member in week one.** Limited training has historically slowed electronic record-keeping adoption in academic labs, so treat onboarding as part of the system rather than an afterthought [1]. ## Common Mistakes and Limitations - **Committing raw instrument dumps.** A repository clogged with hundreds of megabytes of scanner output becomes slow and hostile to browse. Keep raw data on a shared drive or server, list it in `.gitignore`, and record the location in the entry. - **Vague messages.** "Update" and "fix" tell a future reader nothing. A message that names the sample and the reason turns the history into a searchable record. - **Treating Git as a backup drive.** Version control records decisions, not just files. If you only push at the end of the month, you lose the fine-grained history that makes the tool valuable. - **Resolving conflicts by picking the newer date.** Newer is not the same as correct. Check which value the run data supports before deleting a conflict marker. - **Relying on tracked changes in Word documents as your only history.** Tracked changes are easy to accept accidentally, they do not survive format conversions, and they cannot prove who saved what when. - **Assuming revision history equals a compliant record.** Commits establish who changed what and when, but regulated work generally needs explicit approval, which is why electronic signature sits alongside the audit trail as a core ELN capability [2]. Follow your institution's policy for signed records. - **Concentrating expertise in one person.** If a single lab mate holds all the Git knowledge, the notebook fails the day they leave. Rotate the role and keep a one-page workflow taped to the bench manual. - **Rewriting shared history.** Commands that erase or reshuffle past commits break every collaborator's copy. In a shared repository, always correct forward with `git revert`. Two limitations deserve honesty. Git compares text beautifully but treats Word, Excel, and image files as opaque blocks, so diffs are useless for them, which is why the ELN-and-Git pairing works better than either alone. And what counts as a compliant record varies by institution and by funding context, so confirm your lab's requirements with your research integrity or quality office before standardizing on any single system. ## Frequently Asked Questions ### What is version control in a shared lab notebook? It is the practice of saving every change to a shared notebook as a separate, attributed, time-stamped version, so earlier states can be restored and every edit traces back to a person and a date. ### Do I need Git if my electronic lab notebook already saves a revision history? Often no. If your ELN records who changed what and when, lets you read earlier versions, and exports complete records, its built-in history is enough. Git earns its keep for analysis code, long text protocols, and files the ELN handles poorly. ### How often should I commit changes to a shared notebook? Every time you finish one meaningful unit of work, such as a completed entry, a corrected protocol step, or a day of results. In practice that means one to several commits per working day. ### What makes a good commit message for lab records? A short sentence in the present tense that states what changed and why, for example "Change incubation to 30 min at 37 C per optimization run 3". A future reader should understand the change from the message alone. ### How do we handle two people editing the same protocol at once? Git marks the competing lines as a merge conflict, the team chooses or combines the versions in the file, and the resolution is committed. A written rule about who owns which files prevents most conflicts before they occur. ### Can version control replace signatures and sign-offs? No. Commits prove who changed what and when, but regulated work generally needs explicit approval, which is why electronic signature is a standard ELN capability alongside the audit trail [2]. Follow your institution's policy for signed records. ### What should stay out of a Git-backed notebook repository? Bulky raw instrument exports, compressed archives, temporary office lock files, and operating system clutter. List them in `.gitignore`, keep the raw data on a shared drive or server, and note its location in each notebook entry. ### How do we introduce version control to a lab that has never used it? Start with one project, one short training session, and a one-page written workflow, then add the second project only after the first runs smoothly. Structured training matters, because limited training has historically slowed the adoption of electronic documentation in academic labs [1]. ## Sources 1. [Implementation and use of cloud-based electronic lab notebook in a bioprocess engineering teaching laboratory.](https://pubmed.ncbi.nlm.nih.gov/29201138/) 2. [eCAT: Online electronic lab notebook for scientific research.](https://pubmed.ncbi.nlm.nih.gov/20334629/)