Skip to main content

Shen Lab Handbook

5 Git And GitHub

Git and GitHub are used in Shen Lab to organize code, track project history, collaborate with others, and make analyses easier to review and reproduce. Every lab member who writes code should learn the basic Git workflow.

Git is the version-control system. GitHub is an online platform for hosting Git repositories, reviewing changes, managing issues, and collaborating with lab members or external collaborators.

5.1 What To Install

New members should install:

  • Git;
  • a GitHub account;
  • GitHub Desktop, optional but useful for beginners;
  • an editor such as RStudio or Visual Studio Code;
  • command-line access through Terminal, PowerShell, or another shell.

After installation, check Git from the command line:

git --version

5.2 GitHub Account

Create or prepare a GitHub account before working on lab code. Use an account name and profile that collaborators can recognize.

Recommended setup:

  • add your full name or recognizable display name;
  • add your NTU email or another professional email;
  • enable two-factor authentication;
  • set up SSH keys or another secure authentication method;
  • ask the PI or repository owner for access to the relevant organization or repository.

Do not share your GitHub password, personal access token, SSH private key, or recovery codes with anyone.

5.3 Basic Workflow

Most lab projects use a simple workflow:

  1. clone the repository;
  2. create or switch to the correct branch;
  3. pull the latest changes;
  4. edit files;
  5. check what changed;
  6. commit with a clear message;
  7. push changes to GitHub;
  8. open a pull request if review is needed.

Common commands:

git clone REPOSITORY_URL
git status
git pull
git add FILE
git commit -m "Describe the change"
git push

If you are unsure about a shared repository, ask your mentor before pushing.

5.4 Branches

Branches allow you to work on changes without immediately changing the main version of a project.

Good practice:

  • use a new branch for substantial edits;
  • keep branch names short and descriptive;
  • pull the latest changes before starting;
  • avoid doing unrelated work in the same branch;
  • delete merged branches when they are no longer needed.

Example:

git checkout -b update-analysis-script

5.5 Commits

A commit should represent a clear unit of work. Good commit messages make project history easier to understand.

Good commit messages:

  • describe what changed;
  • are specific enough to be useful later;
  • avoid vague messages such as update, fix, or final;
  • separate unrelated changes into different commits when possible.

Examples:

Add sample metadata validation script
Update metabolomics QC figure
Fix file path in preprocessing workflow

5.6 Pull Requests

Pull requests are used to review and discuss changes before merging them.

A good pull request should include:

  • a short summary of the change;
  • why the change was needed;
  • files or workflows affected;
  • tests, checks, or commands that were run;
  • notes about limitations or remaining work.

For manuscripts, websites, packages, or shared analysis pipelines, pull requests help others review changes before they affect the main project.

5.7 What Not To Commit

Never commit:

  • passwords;
  • API keys;
  • access tokens;
  • SSH private keys;
  • identifiable human-subject information;
  • unpublished sensitive data unless the repository is explicitly approved for it;
  • large raw data files unless the project has a clear storage policy;
  • temporary files such as .DS_Store, .RData, .Rhistory, or cache folders.

Use .gitignore to keep local or generated files out of version control.

5.8 GitHub Issues

GitHub Issues can be used to track:

  • bugs;
  • analysis tasks;
  • website updates;
  • documentation needs;
  • discussion points;
  • project to-do items.

Write issues clearly. Include background, expected outcome, current problem, and relevant files or links.

5.9 Lab Practice

For lab projects:

  • keep code in the agreed repository;
  • keep data in the approved storage location;
  • document how to rerun important analyses;
  • avoid changing shared code without communicating with the project owner;
  • use pull requests for changes that affect other people;
  • ask before making destructive changes to shared branches or repositories.

If a repository contains unpublished work, collaborator data, or manuscript materials, confirm sharing and visibility settings with the PI.

5.10 Getting Help

If you run into a Git or GitHub problem, collect:

  • the repository name;
  • the branch name;
  • the command you ran;
  • the exact error message;
  • the output of git status;
  • what you were trying to do.

Then ask your mentor, a relevant lab member, or the PI.