# How to Collaborate on a Scientific Manuscript Using Git and GitHub By the end of this guide, you will be able to turn a manuscript folder into a Git repository, save every edit as a labeled snapshot, invite coauthors to a private GitHub repository, draft changes on branches, merge them through reviewed pull requests, resolve a merge conflict without losing anyone's text, and undo mistakes with restore, reset, and revert. You need a computer with Git installed, a free GitHub account, and a manuscript kept as plain text in Markdown or LaTeX. No programming experience is required. Git is a version control system, a program that records snapshots of your files so you can revisit or undo any change. GitHub is a hosting service that stores Git repositories online and adds the collaboration layer: shared access, review, and discussion. A primer on version control for surgical data science makes the case plainly: computational analysis now sits inside routine clinical research, journals increasingly request code availability statements, and most trainees and faculty still receive no formal training in version control [1]. This guide turns the toolset software teams rely on into a workflow for writing papers. ## Why Git and GitHub Fit Scientific Writing Every coauthor who has traded manuscript_v4_FINAL_revised.docx attachments by email already understands the problem Git solves. Nobody can tell which version is current, who changed which sentence, or whether the methods paragraph that disappeared was ever approved. Version control replaces the attachment chain with one shared repository that holds the full history of every file. For a manuscript, the repository typically contains the text, the analysis scripts, the figure code, and a README explaining how they fit together. When a journal or a reviewer asks how the numbers were produced, the answer is a repository link rather than a scramble through old folders. Major journals now request code availability statements at publication, and reviewers may ask that reported results be regenerated from shared code [1]. GitHub for researchers adds what a bare Git repository lacks: access control so only invited coauthors can write, pull requests so changes are reviewed before they land, and issues so revision requests become a tracked to-do list. The same infrastructure supports multi-institutional projects, where each site works on branches and nothing merges without review [1]. Git for scientists follows the same rules as Git for software teams. The vocabulary is new, the daily loop is small, and the rest of this guide walks through it step by step. ## The Four Mental Models Behind Every Git Command A primer on Git for surgical research organizes the entire tool around four concepts: the repository, the commit, the branch, and the remote [1]. Learn these and every command later in this guide becomes predictable. 1. **Repository.** A repository, or repo, is your project folder plus a hidden subfolder named .git where Git stores every snapshot it has ever been given. The files you see are the working copy. The history lives in .git, which is why deleting that folder deletes the history while leaving your current files in place. 2. **Commit.** A commit is a snapshot you create on purpose, together with a message describing why the change was made and a unique identifier such as 3f9a1c2. Commits are append-only: you add new ones, you do not silently overwrite old ones, which is what makes history trustworthy. 3. **Branch.** A branch is a parallel line of work. main holds the agreed version of the manuscript. A branch named intro-rewrite holds an experiment that might become part of main later. Creating one costs nothing and takes one command. 4. **Remote.** A remote is a copy of the repository on another server, almost always GitHub, and the convention is to name the primary one origin. push sends your commits to the remote, pull brings coauthors' commits down to you. Everything else is detail layered on these four ideas. ## What You Need Before You Start ![Comparison table of Markdown or LaTeX against .docx across line diffs, merge conflicts, and review in pull requests.](/article-images/illustrations/collaborate-on-manuscript-git-github-word-vs-plaintext.webp) Install Git from the official site, git-scm.com, which provides installers for Windows and macOS and packages for Linux. Verify the installation in a terminal: ``` git --version ``` Expected output: ``` git version 2.45.1 ``` Any recent 2.x release works. Create a free account at github.com if you do not have one. If you prefer a graphical interface, GitHub Desktop covers cloning, committing, pushing, and pulling with buttons, and everything in this guide still applies. Two terminal commands are enough for this guide: cd moves you between folders, and ls (dir on Windows) lists the contents of the current folder. Choose a plain-text format for the manuscript before the first commit. Git compares files line by line, which works cleanly on Markdown (.md) and LaTeX (.tex). Word files use a compressed binary format, so Git can report that a .docx changed but cannot show which sentence changed, and it cannot merge two people's edits to the same file. Plain text is what makes line-level review and conflict resolution possible. ## Step-by-Step: Build Your First Manuscript Repository The following walkthrough creates a repository, protects it from day one, and connects it to GitHub. Run the commands in order from a terminal. ### Step 1. Configure your identity ``` git config --global user.name "Alex Rivera" git config --global user.email "arivera@university.edu" git config --global init.defaultBranch main ``` These three settings matter. user.name and user.email are stamped into every commit you make, which is how coauthors later tell who changed what. init.defaultBranch names the first branch main, matching GitHub's default and avoiding a warning Git otherwise prints at init. The, global flag applies the settings to every repository on the machine. Omit it to set values for one repository only. Verify: ``` git config --global -l ``` Expected output: ``` user.name=Alex Rivera user.email=arivera@university.edu init.defaultbranch=main ``` ### Step 2. Create the folder and start tracking it ``` mkdir rct-manuscript cd rct-manuscript git init ``` Expected output: ``` Initialized empty Git repository in /Users/arivera/rct-manuscript/.git/ ``` git init converts the current folder into a repository by creating the hidden .git directory. Your files are untouched. Common error: running a Git command outside the project folder produces: ``` fatal: not a git repository (or any of the parent directories): .git ``` Fix: use cd to move into the project folder and run the command again. ### Step 3. Write the .gitignore before anything else A .gitignore file lists file names and patterns that Git should refuse to track. The surgical Git primer is explicit that identifiable patient data must never enter a version-controlled repository and demonstrates the .gitignore file as the guard against exactly that accident [1]. Write it before the first commit, not after. Create a file named .gitignore in the project folder with contents like these: ``` # Datasets stay in the controlled environment data/ *.csv *.sav *.dta *.xlsx # Word processor lock files ~$*.docx # LaTeX build artifacts *.aux *.log *.out *.synctex.gz # Operating system clutter .DS_Store Thumbs.db ``` Lines starting with # are comments. *.csv matches every CSV file, and data/ ignores an entire folder. Adjust the patterns to your project, then check that they work: git status should list none of the ignored files as untracked. ### Step 4. Add a README and make the first commit Create a short README.md in your editor (or with the printf command shown), then stage and commit: ``` printf "# RCT Manuscript\n\nTarget journal, author list, and analysis plan.\n" > README.md git add .gitignore README.md git commit -m "Start manuscript repository with gitignore and README" ``` Expected output: ``` [main (root-commit) 3f9a1c2] Start manuscript repository with gitignore and README 2 files changed, 6 insertions(+) create mode 100644 .gitignore create mode 100644 README.md ``` git add stages files, meaning it copies them into the staging area, the holding pen for the next commit. git commit -m records the staged snapshot with your message. The string 3f9a1c2 is the shortened commit identifier you will use to refer to this snapshot later. Common error: committing before Step 1 produces: ``` Author identity unknown *** Please tell me who you are. Run git config --global user.email "you@example.com" git config --global user.name "Your Name" to set your account's default identity. fatal: unable to auto-detect email address (got 'arivera@laptop.(none)') ``` Fix: run the two identity commands from Step 1 and commit again. ### Step 5. Connect the repository to GitHub On github.com, sign in, choose New repository, name it rct-manuscript, set visibility to Private, and leave every initialization checkbox unchecked, because your local folder already has a README. GitHub then shows a repository URL. Connect and upload: ``` git remote add origin https://github.com/arivera-lab/rct-manuscript.git git push -u origin main ``` Expected output (trimmed): ``` Enumerating objects: 4, done. Counting objects: 100% (4/4), done. Writing objects: 100% (4/4), 321 bytes | 321.00 KiB/s, done. branch 'main' set up to track 'origin/main'. ``` git remote add origin registers the GitHub URL under the name origin, the conventional name for your project's primary remote. git push uploads commits. The -u flag records the link between your local main and GitHub's main so that every later push and pull works without extra arguments. Check the connection: ``` git remote -v ``` Expected output: ``` origin https://github.com/arivera-lab/rct-manuscript.git (fetch) origin https://github.com/arivera-lab/rct-manuscript.git (push) ``` Refresh the GitHub page in your browser. The README and .gitignore should be visible, which confirms the push worked. ### Step 6. Invite coauthors On the repository page, open Settings, choose Collaborators, and add people by GitHub username or email. Each coauthor accepts an email invitation and gains write access to this private repository. They then download a full copy with: ``` git clone https://github.com/arivera-lab/rct-manuscript.git cd rct-manuscript ``` git clone downloads the repository with its entire history and connects it to origin automatically, so pull and push work immediately after cloning. ## The Daily Edit-Stage-Commit Cycle The primer describes the edit-stage-commit loop as the dominant daily workflow, and it is the loop you will repeat hundreds of times on a manuscript [1]. Edit files in any editor, stage what you want to save, commit it with a message, and push so coauthors receive it. Work through one cycle. First, see what changed: ``` git status ``` Expected output: ``` On branch main Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git restore ..." to discard changes in working directory) modified: manuscript.md no changes added to commit (use "git add" and/or "git commit -a") ``` Second, inspect the edits line by line: ``` git diff manuscript.md ``` Expected output (excerpt): ``` @@ -12,7 +12,7 @@ -The intervention improved adherence. +The intervention improved medication adherence. ``` Lines starting with - are the old text, lines starting with + are the new text, and the @@ line locates the change. Third, stage and commit: ``` git add manuscript.md git commit -m "Methods: specify that adherence means medication adherence" ``` Expected output: ``` [main 8c4d2e1] Methods: specify that adherence means medication adherence 1 file changed, 1 insertion(+), 1 deletion(-) ``` Fourth, share and review the history: ``` git push git log --oneline ``` Expected output: ``` 8c4d2e1 (HEAD -> main) Methods: specify that adherence means medication adherence 3f9a1c2 Start manuscript repository with gitignore and README ``` HEAD is Git's name for the commit you are currently on. The staging step is not bureaucracy: it lets you commit one file now and another later, which keeps each snapshot about one thing. Commit messages should say why the change matters. "Methods: specify that adherence means medication adherence" tells a coauthor what to look for. "update" tells them nothing. The table below collects the commands that carry a manuscript project. | Command | What it does | When to use it | |, - |, - |, - | | git status | Lists changed, staged, and untracked files | Start and end of every session | | git diff | Shows unstaged edits line by line | Before staging | | git diff, staged | Shows exactly what the next commit will contain | Before committing | | git add | Stages a file for the next commit | When an edit is ready to save | | git commit -m "message" | Saves a snapshot with a message | After staging | | git push | Uploads commits to GitHub | End of a work session | | git pull | Downloads and merges coauthors' commits | Start of a work session | | git log, oneline | Prints a compact history | Finding a commit identifier | | git switch -c | Creates a branch and moves onto it | Before starting a new task | | git restore | Discards uncommitted edits to a file | When an experiment failed | | git reset HEAD~1 | Undoes the last commit, keeps the edits | Wrong message or wrong content | | git revert | Adds a new commit that undoes an old one | Fixing shared history safely | ## Step-by-Step: Collaborate on the Manuscript with Git and GitHub Branches and pull requests are the collaboration mechanism the primer emphasizes, and they replace the reply-all email thread [1]. The rule on a shared manuscript is simple: nobody edits main directly. Work happens on a branch, and it reaches main only through a pull request a coauthor has reviewed. ### Step 7. Branch before you write ``` git switch -c abstract-draft ``` Expected output: ``` Switched to a new branch 'abstract-draft' ``` git switch -c creates the branch and moves you onto it in one command. On Git versions older than 2.23, `git checkout -b abstract-draft` does the same thing. Run `git branch` at any time to list branches, with an asterisk marking where you are. Commits now land on abstract-draft while main stays untouched. ### Step 8. Commit on the branch and push it Draft abstract.md, then: ``` git add abstract.md git commit -m "Draft abstract with background, methods, and results" git push -u origin abstract-draft ``` Expected output (trimmed): ``` Enumerating objects: 4, done. ... remote: Create a pull request for 'abstract-draft' on GitHub by visiting: remote: https://github.com/arivera-lab/rct-manuscript/pull/new/abstract-draft Branch 'abstract-draft' set up to track 'origin/abstract-draft'. ``` The branch now exists on GitHub, visible to every coauthor, and GitHub hands you the link for the next step. ### Step 9. Open a pull request A pull request (PR) is a proposal on GitHub to merge one branch into another, wrapped in a discussion thread where coauthors comment on lines, request changes, and finally approve. Open the link from the push output, or go to the repository page, choose Pull requests, then New pull request. Set base to main and compare to abstract-draft. Write a description that answers two questions: what changed, and what should a reviewer check. Request a specific coauthor as the reviewer so the request does not sit unowned. ### Step 10. Review and merge The reviewer reads the diff, leaves line comments, and either approves or requests changes. Requested changes are handled with more commits on the same branch, and the pull request updates automatically. Once approved, click Merge pull request, or Squash and merge, which folds the branch's commits into one tidy commit on main. GitHub then offers a button to delete the branch. Clean up locally and sync: ``` git switch main git pull git branch -d abstract-draft ``` Expected output: ``` Deleted branch abstract-draft (was 4e2f8a9). ``` The -d flag deletes a branch only when its work is merged, so it cannot silently destroy anything. ### Step 11. Pull before every session If a coauthor merged work while you were editing, a push is rejected: ``` To https://github.com/arivera-lab/rct-manuscript.git ! [rejected] main -> main (fetch first) error: failed to push some refs to 'https://github.com/arivera-lab/rct-manuscript.git' hint: Updates were rejected because the remote contains work that you do not have locally. ``` Nothing was lost. Integrate the remote work and try again: ``` git pull git push ``` If you both edited the same lines, the pull stops with a conflict, which is the next step. ### Step 12. Resolve a merge conflict A conflict means two branches changed the same lines and Git will not choose for you. The pull output names the file: ``` Auto-merging manuscript.md CONFLICT (content): Merge conflict in manuscript.md Automatic merge failed. Fix conflicts and then commit the result. ``` Run git status to see every conflicted file, listed as "both modified". Open the file and find the markers: ``` <<<<<<< HEAD Rituximab-based therapy remains the standard first-line approach. ======= Rituximab-based chemoimmunotherapy remains the standard first-line approach. >>>>>>> add-limitations ``` The text between <<<<<<< and ======= is your version. The text between ======= and >>>>>>> is the incoming version. Keep the wording you want, or blend the two, delete the three marker lines, and save. Then finish: ``` git add manuscript.md git commit ``` The editor opens with a prepared merge message, save and close it. Confirm with git status, which should report a clean tree, and git log, oneline, which now shows the merge commit. Conflicts sound alarming and are usually resolved in a few minutes of editing. ## Keep Patient Data Out of the Repository The primer states the rule as policy: identifiable patient data must never enter a version-controlled repository, and the .gitignore file is the mechanism that enforces it [1]. A repository holds text, code, and small configuration files. Raw datasets, exports that carry identifiers, and anything else governed by your data use agreement stay in the controlled environment where the data live. Three practices make the rule hold under pressure. First, write the .gitignore before the first commit and verify it with git status. Second, keep credentials out of scripts: read API keys and database passwords from environment variables or from a config file listed in .gitignore, because a committed password is visible to everyone with repository access. Third, know the incident path. Deleting a sensitive file in a later commit does not remove it, since every commit keeps a snapshot and anyone with access can view old ones. Repairing that requires rewriting history with a tool such as git filter-repo, forcing the rewritten history to GitHub, and having every collaborator re-clone, after which you should still treat the exposure as an incident and involve your institutional research data office or IT security team. Prevention costs one file written once. Cleanup costs a bad week. ## Fixing Mistakes: Three Recovery Scenarios ![Decision tree asking whether the work is committed and whether it was pushed, leading to git restore, git reset, or git revert.](/article-images/illustrations/collaborate-on-manuscript-git-github-recovery-choice.webp) The primer closes with recovery scenarios, because version control only pays off when you trust it during a crisis [1]. Three scenarios cover most manuscript emergencies, and all of them use commands you have already seen in the table. ### Scenario 1. Discard uncommitted edits to a file ``` git restore manuscript.md ``` This returns manuscript.md to its state at the last commit. The discarded edits are gone permanently, so run git diff first and confirm you do not need them. ### Scenario 2. Undo the last commit but keep the work ``` git reset HEAD~1 ``` Expected output: ``` Unstaged changes after reset: M manuscript.md ``` HEAD~1 means one commit before the current one. The commit disappears from history and its edits return to your folder as unstaged changes, ready to recommit with a better message or different content. Two variants change where the edits end up:, soft keeps them staged, and, hard deletes them along with the commit. Avoid, hard on a shared manuscript unless you have checked twice, because it destroys the edits themselves. Confirm the result with git log, oneline and git status. ### Scenario 3. Undo a commit that is already on GitHub Never rewrite commits that coauthors may have pulled. Add a new commit that reverses an old one: ``` git revert 8c4d2e1 ``` Expected output: ``` [main 2f6a9b4] Revert "Methods: specify that adherence means medication adherence" 1 file changed, 1 insertion(+), 1 deletion(-) ``` History keeps both the mistake and its reversal, which is exactly what shared history needs. If the message on your last commit was simply wrong and nobody has pulled yet, `git commit, amend -m "Methods: define medication adherence precisely"` replaces it. Amend only before pushing, because amending a pushed commit forces every coauthor to untangle their copy. ### The safety net If a reset goes wrong, git reflog lists where HEAD has been: ``` 2f6a9b4 (HEAD -> main) HEAD@{0}: revert: Revert "Methods: specify that adherence" 8c4d2e1 HEAD@{1}: commit: Methods: specify that adherence means medication adherence 3f9a1c2 HEAD@{2}: commit (initial): Start manuscript repository with gitignore and README ``` Commits listed here can be restored with `git reset 8c4d2e1` even after a bad reset, because Git keeps discarded commits for a grace period before cleaning them up. Check the result with git log, oneline afterward. ## Tips for Manuscript Collaboration with Git and GitHub These habits separate teams that enjoy the workflow from teams that tolerate it. 1. Commit small and often. One commit per section edit beats one commit per week, and small commits make review and revert precise. 2. Keep branches short-lived. One branch per task, merged within days. A branch that lives for a month will collide with main. 3. Pull at the start of every session and push at the end. This single habit prevents most conflicts and all stale-copy surprises. 4. Use GitHub Issues as the shared revision list. An issue is a numbered discussion thread on the repository. Reference the number in commit messages, for example "Abstract: address the gap statement point (issue 4)", and GitHub links the commit to the thread. 5. Protect main. In the repository settings, branch protection can require a pull request review before anything merges, so nobody bypasses review by accident. 6. Snapshot the submission with a tag: ``` git tag -a v1.0-submission -m "Version submitted to the target journal" git push origin v1.0-submission ``` A tag is a permanent name for a commit, which is what you cite when a reviewer asks which exact version produced the figures. 7. Stash when interrupted. If a pull refuses because of your local edits with "error: Your local changes to the following files would be overwritten by merge", run `git stash`, pull, then `git stash pop` to restore your edits on top of the updated files. 8. Agree on plain text early. If part of the team must circulate Word files, name one person who merges, because Word edits cannot be combined line by line. Many teams draft in Markdown and convert to .docx with the pandoc tool for Word-preferring coauthors. 9. Write pull request descriptions for the reviewer: what changed, what to check, and which issue it closes. 10. Extend the workflow when a tool earns its keep. The primer demonstrates installing community-developed software, using Stash, an open-source persistent memory layer for AI research assistants, as its worked example [1]. Add tooling after the core loop is a habit, not before. ## Common Mistakes and Limitations 1. Initializing Git in a folder that already holds data. The first commit captures whatever is present, including files you meant to exclude. Write the .gitignore first and check git status before the first add [1]. 2. Committing straight to main on a shared repository. Review happens in pull requests, so direct commits to main belong only in solo projects or trivial fixes [1]. 3. Vague commit messages. "fix" and "update" tell a coauthor nothing six weeks later. Write why the change was made. 4. Monster commits. Bundling text edits, new analysis code, and regenerated figures into one commit makes review slow and undo coarse. Split them. 5. Editing for a week without pulling or pushing. Long-lived local copies guarantee painful conflicts. Pull daily. 6. Treating Word files as version-controlled text. Git stores .docx but cannot show sentence-level diffs or merge cleanly. Draft in Markdown or LaTeX when the team allows it. 7. Deleting a sensitive file and assuming it is gone. History keeps every snapshot, so old versions remain reachable by anyone with access. Use the incident path described in the data section. 8. Force pushing to a shared branch. `git push, force` overwrites coauthors' commits with yours. Use git revert instead, and enable branch protection so the mistake cannot happen. 9. Committing credentials, raw data, or huge generated files. Use .gitignore patterns, environment variables, and controlled storage for anything that is not text you wrote. 10. Skipping identity configuration, then hitting the "Author identity unknown" error on the first commit. The two config commands from Step 1 fix it in under a minute. Limitations: Git rewards a few weeks of practice, and the first month feels slower than the email attachment habit it replaces. Converting a Word-preferring team to plain text takes diplomacy. Any project touching human data needs review against your institutional data governance policy before the first commit, and unusual setups such as external partners or regulated data deserve a conversation with your research data office or IT security team. Individual situations differ, so treat this workflow as a starting point to adapt with the people who govern your data. ## Frequently Asked Questions ### Do I need to know how to program to use Git for a manuscript? No. About a dozen commands cover daily manuscript work, and GitHub's web interface handles review, comments, and merging through buttons. The real adjustment is the habit of committing small changes with clear messages. ### What is the difference between Git and GitHub? Git is the version control program that runs on your computer and records snapshots. GitHub is a website that hosts Git repositories and adds sharing, review, and issue tracking. You can use Git alone, but collaboration needs a remote such as GitHub. ### Can I use Git and GitHub with Microsoft Word files? Yes, Git will store and version Word files, but it cannot show line-by-line diffs or merge conflicts cleanly because .docx is a compressed binary format. Plain text formats such as Markdown or LaTeX get the full benefit. ### Is GitHub safe for an unpublished manuscript? A private repository is visible only to people you invite, which suits manuscripts under review. Keep patient data and restricted material out of the repository regardless of its visibility. ### How do I undo a commit I already pushed? Use git revert with that commit's identifier. It adds a new commit that reverses the old change while leaving shared history intact, so coauthors keep a consistent copy. ### How do I fix a merge conflict? Open the conflicted file, delete the three marker lines Git inserts around the clashing text, keep the wording you want, then stage the file and commit. Run git status afterward to confirm nothing is left unresolved. ### Should coauthors fork the repository or share branches? Coauthor teams should share branches inside one private repository, because everyone needs write access and review happens in pull requests. Forks, meaning personal copies on GitHub, suit outside contributors who should not have write access. ### How do I handle a journal's code availability statement? Publish the analysis code in a public GitHub repository, tag the version used for the submission, and cite that repository in the manuscript. Many journals now request such a statement at submission. ## Sources 1. [Version Control for Surgical Data Science: A Primer on Git and GitHub.](https://pubmed.ncbi.nlm.nih.gov/42893433/)