# 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:

git --version

---
## 5. Set up your Git identity

You only need to do this once on a computer.

git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

Check your settings:

git config --global --list

---

## 6. Create a new project folder

Example:

mkdir my_scRNAseq_project
cd my_scRNAseq_project

Initialize Git:

git init

Now this folder is a Git repository.

---

## 7. Recommended project structure for bioinformatics

A simple structure:

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:

# 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:

touch .gitignore

Then edit it using your text editor.

---

## 10. Check project status

To see what has changed:

git status

This tells you which files are:

- Untracked
- Modified
- Staged
- Ready to commit

---

## 11. Add files to Git

Add one file:

git add README.md

Add everything:

git add .

Be careful with `git add .`.

Always check first:

git status

---

## 12. Commit your changes

A commit is a saved checkpoint.

git commit -m "Initial project setup"

Good commit messages are short but informative.

Examples:

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:

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:

git remote add origin https://github.com/your_username/my_scRNAseq_project.git

Push your code:

git branch -M main
git push -u origin main

---

## 14. Clone an existing repository

To download a GitHub repo:

git clone https://github.com/username/repository_name.git

Then enter the folder:

cd repository_name

---

## 15. Pull updates from GitHub

Before working, especially in a shared project:

git pull

This downloads the latest changes from GitHub.

---

## 16. A simple daily workflow

A common workflow:

git status
git pull
# edit scripts
git status
git add .
git commit -m "Describe what changed"
git push

For example:

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:

# 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:

conda env create -f env/environment.yml
conda activate my_env