Computing · Practical guide
Git & GitHub for research
Keep research code organized, record changes clearly, and work with branches and large files using a reproducible version-control workflow.
Start learning01Edit02Commit03Share
What you’ll learn
- Connect a local repository to GitHub.
- Record changes and compare development branches.
- Track large files and reproduce a historical model version.
Before you begin Terminal basics
- Git installed and a GitHub account.
- Git LFS for the large-file section.
- Replace example repository names, email addresses, and paths with your own.
01
Connect to GitHub
Create an SSH key if you need one, add the public key to your GitHub account, then test the connection.
Follow GitHub’s SSH setup instructions for adding the key to the agent and account.
# Create a key only if you do not already have a suitable one.
ssh-keygen -t ed25519 -C "your_email@example.com"
# Add the PUBLIC .pub key to GitHub using its SSH setup guide.
# Then test the connection.
ssh -T git@github.com
02
Record and share changes
Clone the repository, review the working tree, stage the files you intend to publish, and create a descriptive commit.
git clone git@github.com:YOUR_USERNAME/YOUR_REPOSITORY.git
cd YOUR_REPOSITORY
git status
git diff
git add README.md
git commit -m "Describe the change"
git push origin main
# For a new local repository, rather than an existing clone:
# git remote add origin git@github.com:YOUR_USERNAME/YOUR_REPOSITORY.git
# git push -u origin main
03
Work with branches
Create a branch for a change, commit there, and merge it into the main branch after review.
mainfeaturemerge
git switch -c feature-analysis
# Edit your analysis, then review and record the changes.
git diff
git add analysis.py
git commit -m "Add analysis workflow"
git push -u origin feature-analysis
# After review, merge the branch into main.
git switch main
git merge feature-analysis
git push origin main
git branch -d feature-analysis
04
Manage large files with Git LFS
Track a file pattern, commit the .gitattributes file, and add the large file. LFS stores a pointer in Git and manages the file content separately.
git lfs install
git lfs track "data/large_file.zip"
git add .gitattributes
git add "data/large_file.zip"
git commit -m "Track research archive with Git LFS"
git push origin main
# After cloning a repository that uses LFS:
git lfs ls-files
git lfs pull
05
Reproduce a CLM model version
Use the original Arctic carbon-cycle update example to compare a version containing the updates with the version immediately before them.
git clone https://github.com/ESCOMP/CTSM.git
cd CTSM
git log --oneline
# Updated version in the original example.
git switch -c abz_updates dd0cbec
git log --oneline -5
# Version before the original update series.
git switch -c no_abz 384c726
git branch
git diff no_abz..abz_updates