# GitHub Tutorial for Bioinformatics and Computational Biology
## 1. Why use GitHub?
GitHub is a platform for storing, version-controlling, sharing, and documenting code.
For bioinformatics and computational biology, GitHub is especially useful for:
- Keeping track of analysis scripts
- Recording changes to code over time
- Sharing reproducible workflows
- Collaborating with lab members
- Documenting software, pipelines, and tutorials
- Building a visible research portfolio
In short:
> Git tracks your code history.
> GitHub lets you store and share that history online.
---
## 2. Git vs GitHub
These two are related but not the same.
| Tool | What it does |
|---|---|
| Git | A version control system on your computer |
| GitHub | An online platform that hosts Git repositories |
You use **Git** locally, then push your work to **GitHub**.
---
## 3. Basic vocabulary
| Term | Meaning |
|---|---|
| Repository / repo | A project folder tracked by Git |
| Commit | A saved snapshot of your changes |
| Branch | A separate version of your project |
| Push | Upload local commits to GitHub |
| Pull | Download updates from GitHub |
| Clone | Download a GitHub repo to your computer |
| README | The front page documentation of a repo |
| `.gitignore` | A file telling Git what not to track |
---
## 4. Install Git
Check whether Git is already installed:
```bash
git --version
```
---
## 5. Set up your Git identity
You only need to do this once on a computer.
```bash
git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"
```
Check your settings:
```bash
git config --global --list
```
---
## 6. Create a new project folder
Example:
```bash
mkdir my_scRNAseq_project
cd my_scRNAseq_project
```
Initialize Git:
```bash
git init
```
Now this folder is a Git repository.
---
## 7. Recommended project structure for bioinformatics
A simple structure:
```text
my_scRNAseq_project/
├── README.md
├── scripts/
│ ├── 01_qc.py
│ ├── 02_clustering.py
│ └── 03_marker_analysis.py
├── notebooks/
│ └── exploratory_analysis.ipynb
├── results/
│ ├── figures/
│ └── tables/
├── data/
│ └── README.md
├── env/
│ └── environment.yml
├── docs/
│ └── notes.md
└── .gitignore
```
Suggested usage:
| Folder | Purpose |
|---|---|
| `scripts/` | Main reusable analysis scripts |
| `notebooks/` | Exploratory work |
| `results/` | Figures and result tables |
| `data/` | Data information, not usually raw data |
| `env/` | Conda or pip environment files |
| `docs/` | Notes, protocol, methods explanation |
---
## 8. What should not be uploaded?
In bioinformatics, avoid uploading:
- Raw sequencing data
- Large `.fastq`, `.bam`, `.h5ad`, `.rds`, `.loom`, `.h5` files
- Private patient or clinical data
- Passwords or API keys
- Huge intermediate files
> GitHub officially recommends keeping repositories under 1 GB, and strongly recommends staying under 5 GB for performance and maintainability. Individual files over 100 MB are blocked entirely.
Instead, upload:
- Scripts
- Small example data
- Metadata templates
- Documentation
- Environment files
- Instructions for downloading or generating data
## 9. Create a `.gitignore`
Therefore, it is important to setup .gitignore.
A `.gitignore` file tells Git which files to ignore.
Example `.gitignore` for bioinformatics:
```gitignore
# Large data files
*.fastq
*.fastq.gz
*.fq
*.fq.gz
*.bam
*.sam
*.cram
*.vcf
*.vcf.gz
*.h5
*.h5ad
*.rds
*.loom
# Large folders
data/raw/
data/processed/
results/intermediate/
# Python
__pycache__/
*.pyc
.ipynb_checkpoints/
# R
.Rhistory
.RData
.Rproj.user/
# Conda environments
.conda/
.env/
# System files for Mac users
.DS_Store
# Secrets
*.key
*.pem
.env
config_private.yaml
```
Create the file:
```bash
touch .gitignore
```
Then edit it using your text editor.
---
## 10. Check project status
To see what has changed:
```bash
git status
```
This tells you which files are:
- Untracked
- Modified
- Staged
- Ready to commit
---
## 11. Add files to Git
Add one file:
```bash
git add README.md
```
Add everything:
```bash
git add .
```
Be careful with `git add .`.
Always check first:
```bash
git status
```
---
## 12. Commit your changes
A commit is a saved checkpoint.
```bash
git commit -m "Initial project setup"
```
Good commit messages are short but informative.
Examples:
```bash
git commit -m "Add Scanpy QC script"
git commit -m "Update clustering workflow"
git commit -m "Fix marker gene plotting function"
git commit -m "Add conda environment file"
```
Avoid vague messages like:
```bash
git commit -m "update"
git commit -m "stuff"
git commit -m "final final version"
```
---
## 13. Create a GitHub repository
On GitHub:
1. Go to GitHub.
2. Click **New repository**.
3. Choose a repository name.
4. Choose public or private.
5. Do not initialize with README if you already have one locally.
6. Click **Create repository**.
Then connect your local repo to GitHub.
Example:
```bash
git remote add origin https://github.com/your_username/my_scRNAseq_project.git
```
Push your code:
```bash
git branch -M main
git push -u origin main
```
---
## 14. Clone an existing repository
To download a GitHub repo:
```bash
git clone https://github.com/username/repository_name.git
```
Then enter the folder:
```bash
cd repository_name
```
---
## 15. Pull updates from GitHub
Before working, especially in a shared project:
```bash
git pull
```
This downloads the latest changes from GitHub.
---
## 16. A simple daily workflow
A common workflow:
```bash
git status
git pull
# edit scripts
git status
git add .
git commit -m "Describe what changed"
git push
```
For example:
```bash
git status
git add scripts/01_qc.py
git commit -m "Add mitochondrial filtering to QC script"
git push
```
---
## 17. Writing a useful README
Every bioinformatics repo should have a clear `README.md`.
A simple README structure:
```{md}
# Project title
## Overview
Briefly describe the project.
## Data
Describe the dataset used.
Do not upload private or large raw data directly unless appropriate.
## Environment
Explain how to install dependencies.
Example:
```{bash}
conda env create -f env/environment.yml
conda activate my_env
```
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet