1.6 Managing and Sharing Scientific Projects#
Creating and Publishing a GitHub Repository#
Git is a version control system that tracks changes to files over time. GitHub is an online platform for hosting Git repositories, allowing you to back up your work, share it with others, and collaborate on scientific projects.
A Git repository exists independently on your computer. You can make changes, create commits, and review previous versions without an internet connection. To share your work through GitHub, you must create a repository on GitHub and connect it to your local repository.
1. Create a Local Git Repository#
Open a terminal, navigate to your project directory, and initialize Git:
cd ~/myproject
git init -b main
This creates a hidden .git directory containing the repository’s version history and configuration. The -b main option names the initial branch main.
Before committing files, create a .gitignore file identifying files that should not be tracked. For example, a scientific Python project might exclude:
.ipynb_checkpoints/
__pycache__/
*.pyc
_build/
Now stage and commit your project files:
git add .
git commit -m "Initial project commit"
The git add command stages files for inclusion in the next commit, while git commit records a snapshot of those staged changes in the local repository.
Check the repository status:
git status
If all changes have been committed, Git will report:
On branch main
nothing to commit, working tree clean
Note: If Git has not been configured with your identity, you may first need to run:
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
2. Create a Repository on GitHub#
Sign in to GitHub.
Select New repository, or visit github.com/new.
Choose a repository name, such as
myproject.Select Public or Private visibility.
Do not initialize the repository with a README,
.gitignore, or license if these files are already managed in your local repository.Click Create repository.
GitHub will create an empty remote repository that can receive your local commits.
3. Configure SSH Authentication#
GitHub requires secure authentication when pushing changes. One approach is to use SSH (Secure Shell), which authenticates your computer using a cryptographic key pair.
An SSH key pair consists of:
A private key, stored securely on your computer and never shared.
A public key, which can be registered with GitHub.
First, check whether you already have SSH keys:
ls -la ~/.ssh
Look for files such as id_ed25519 and id_ed25519.pub.
Test whether SSH authentication with GitHub is already configured:
ssh -T git@github.com
If it succeeds, GitHub will respond with a message similar to:
Hi username! You've successfully authenticated, but GitHub does not provide shell access.
If SSH authentication is not configured, generate a new key:
ssh-keygen -t ed25519 -C "your-email@example.com"
Accept the suggested filename if it does not overwrite an existing key, and consider protecting the private key with a passphrase.
Start an SSH agent and add your private key:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
Display your public key:
cat ~/.ssh/id_ed25519.pub
Copy the public key and add it to your GitHub account under Settings → SSH and GPG keys → New SSH key:
https://github.com/settings/keys
Then test the connection again:
ssh -T git@github.com
On the first connection, verify GitHub’s SSH host key fingerprint against its published documentation before accepting it.
Important: Never upload, email, or share your private SSH key. Only the public key (the file ending in .pub) should be added to GitHub.
4. Connect the Local Repository to GitHub#
From your project’s directory, connect the local repository to the GitHub repository:
git remote add origin git@github.com:USERNAME/myproject.git
Replace USERNAME with your GitHub username and myproject with your repository name.
Here, origin is the conventional name assigned to the remote repository.
Verify the connection:
git remote -v
The output should resemble:
origin git@github.com:USERNAME/myproject.git (fetch)
origin git@github.com:USERNAME/myproject.git (push)
If you previously configured an HTTPS remote and want to switch to SSH, use:
git remote set-url origin git@github.com:USERNAME/myproject.git
5. Push Your Repository to GitHub#
Push your local commits to GitHub:
git push -u origin main
The -u option establishes the upstream tracking relationship between your local main branch and GitHub’s main branch.
After the first successful push, future uploads can usually be performed using simply:
git push
Visit your GitHub repository in a browser to verify that your project files are available online.
6. The Everyday Git Workflow#
After modifying files, such as Python scripts, Jupyter notebooks, or experimental datasets, the typical workflow is:
# Inspect changes
git status
# Stage modified and new files
git add .
# Record a local snapshot
git commit -m "Add data analysis notebook"
# Upload commits to GitHub
git push
To retrieve changes made to the remote repository:
git pull
The distinction between these commands is important:
Command |
Purpose |
|---|---|
|
Examine the current repository state |
|
Stage changes for the next commit |
|
Record changes in local version history |
|
Upload local commits to GitHub |
|
Retrieve and integrate remote changes |
|
Create a local copy of an existing remote repository |
Scientific computing consideration: Git is well suited to notebooks, source code, documentation, and smaller configuration files. Large experimental datasets, credentials, API keys, and generated output files should not automatically be committed. These may require other data-management approaches, such as Git LFS, data repositories, or explicit download instructions.
The Git repository, together with an environment configuration such as environment.yml, can help other researchers retrieve a project and reproduce its computational environment.