Contents

  1. Overview
  2. Installing Git
  3. Authenticating to GitHub
  4. Notifications
  5. Basic Commands
  6. Markdown
  7. SCM Best Practices
  8. Git Cheat Sheet
  9. Additional Resources

Overview

Git is an open source version control system. A version control system is a piece of software that allows you to track changes in text files over the development lifetime. GitHub is an online platform that allows people to host Git repositories (that is, version controlled projects) online so that other team members and community members have easy access to those repositories. GitHub also offers several additional services like issue tracking, actions, and project boards which we use to manage lab projects. Since the lab is dedicated to open science and all projects are open source, GitHub provides these services for free.

Git is used as the main way to version control projects within our lab. Projects have branches, which are similar to sandboxes where a contributor to a project can safely make changes before requesting that their changes be reviewed by a colleague and ultimately added to the main project. Git also provides utilities to display the changes that have been made to a specific branch, show how files have been edited, and output a log of all changes. All changes are tagged with the author and time to help contributors understand how and when a feature (beneficial change) or a fix (change that corrects a problem) was added.

GitHub is where we will store these repositories. There are several alternatives that provide similar features or features that GitHub does not have. The reason that we picked GitHub over its alternatives (like GitLab or BitBucket) was due to GitHub’s particular feature set, industry and community usage, and available resources, primarily: usage of Git, issues workflow, and first- and third-party project management utilities.

This Git tutorial focuses on using the command-line interface (CLI) tool. We will not be covering any GUI clients because these clients can differ in looks and navigation across operating systems and may be frequently updated whereas the CLI tool has the same interface across operating systems and rarely changes in appearance. (Plus, it’s very handy to know how to use the command line!)

Installing Git

Mac

  1. Open Terminal, which is your built-in shell. If you haven’t don’t this before, start here.
  2. Install Homebrew by following the instructions on the Homebrew homepage to paste a specific command into your Terminal. (When it asks for your sudo password, input the login password for your Mac and hit Enter. It won’t look like you are typing anything on the screen, but you are!)
  3. Still inside your Terminal, type: brew install git
  4. If you encounter issues, check out the main download page, direct from Git.

Windows

  1. Determine whether your computer is 32-bit or 64-bit. This information is available in your system settings under “About.” If you don’t know where to find this, do some quick googling.
  2. Download the appropriate version for your computer’s system type.
  3. Install as you would any other application.

Linux

Use the package manager that comes with your distribution and install git. See specific instructions here.

Authenticating to GitHub

When working in the shell and pushing your work to GitHub, GitHub needs to know who you are. This means you must “authenticate” yourself to the platform. You can do this one of three ways:

  • inputting your username and password every time (very onerous and therefore not recommended!)
  • using SSH keys (preferred for the hpc)
  • creating a personal access token (easiest option for GitHub)

For simplicity, the personal access token is recommended. Authenticate by following these simple instructions, directly from GitHub.

For details on other authentication options, check out this resource page.

Notifications

You can control whether GitHub sends you web notifications, e-mail notifications, or both when you are @mentioned inside GitHub. In this way, when someone tags you on GitHub, you will receive an e-mail, and you will also be able to access the message from the 🔔 icon in the top-right corner of the GitHub webpage.

To ensure that you see these messages (especially when you are first learning GitHub), it is recommended that you select both “Email” and “Web and Mobile” under the Notifications tab of your Account Settings.

Basic Commands

Git has several common commands that will be necessary to properly work with the the lab’s repositories. These are status, add, commit, push, pull, and checkout.

status

This command is your best friend. It will list files and their state within git. Use it often!

Files can either be ignored, untracked, unstaged, or staged. Ignored means that the file satisfies a rule in the .gitignore file and Git pretends it isn’t there. Untracked refers to files that Git is not ignoring but have never been committed; this is normal for newly created files. Unstaged files are tracked files that currently have changes but haven’t been placed in the staging area for the next commit. Staged files are ready for the next commit.

Example:

git status

add

This command will add any file (tracked or untracked) to the staging area for the next commit.

Example:

git add some_file.txt

Note: you can also use git add . to add all unstaged files to the staging area for the next commit.

clone

This command creates a clone of the remote repository on your local machine so that you can make changes (which you will ultimately upload back to the remote repository to share with collaborators).

Example:

# in local folder into which you want the copy the GitHub contents
git clone <link to remote repository to be cloned>
# new folder is added to your local folder

checkout

This command changes the contents of the local repository to match the branch that you “checkout”. It will leave changed files untouched so that you can commit them to the branch you are checking out. This is useful when you accidentally made changes to “branch_b” thinking you were on “branch_a”.

Example:

# on branch_b
git checkout branch_a
# on branch_a
# changes were brought over

commit

This command will commit your changes to the repository. There are two important options for commit -m (required) and -a (optional).

  • -m is for adding the commit message, which you should always do
  • -a means that git will automatically add any tracked files to the staging are and include in your commit (even if you forgot to add them to the staging area yourself). If you don’t always check git status before you commit, you may want to use -a to ensure you don’t leave changes behind.

Example:

# Staged files: s.txt
# Unstaged files: u.txt
# Untracked and unstaged files: uu.txt

# first example
git commit -m "Update s file"
# Commits only changes for s.txt

# Reset
# Second example
git commit -am "Update s and u file"
# Adds u.txt to staging area
# Commits changes for s.txt and u.txt

push

This command will push all committed changes from your local computer to the remote repository.

Example:

# Your working branch is feature-joe
git push origin feature-joe
# Changes are uploaded from your local to the remote

pull

This command will “pull” changes from the remote repository to your local. Pull will try to fetch any new changes and merge them. Generally, as long as you have not diverged from the remote repository this will work fine.

Example:

# Local repository is behind remote repository but has not diverged
git pull
# Git will download new changes and merge them automatically

Markdown

GitHub supports markdown, which allows you format text in text-based .md files so that GitHub renders them beautifully online. The Get with Git training includes a module on markdown. Here are some other helpful guides: GitHub Guide to Mastering Markdown GitHub Markdown Cheatsheet

SCM Best Practices

When working with Git and GitHub for the lab, remember these best practices for source code management (SCM):

Commit often.

Don’t make too many changes without commits, since it can be destructive if one change within the commit is bad. Commit often and leave a detailed comment about what part of the code was changed.

Check your version.

Make sure you are working on the latest version. Use the latest version to avoid accidentally changing an old version and causing confusion.

Be obsessive about note-taking.

Make detailed notes/comments about everything you do. This should be 2-3 sentences that thoroughly describe the changes made (what was changed, why it was changed, etc.).

Example: Added indentation on Line 13 for readability. Corrected error, changed dog.jpg to dog.jpg on Line 27.

Review changes before committing.

Be 100% sure you want to commit the changes made before doing so!

Use branches.

Work independently but communicate what you are working on by creating a new branch and naming it according to the lab’s nomenclature.

Agree on a team workflow.

Decide with your team who is editing code, what they are editing, and why they are editing. Communicate frequently to stay on track.

Git Cheat Sheet

Command Description
ls Checks your current path
cd Change your directory
git branch [BRANCH NAME] Creates a new branch
git checkout [BRANCH NAME] To actually enter a branch
git status Checks what branch you’re on. Also tells you if any changes were made to a file (i.e any unstaged changes, new commits)
git add [PATH OF FILE(S) LOCATION] Adds contents to the staging area
git commit -m "[MESSAGE]" Commits a change (check out the lab’s conventions for commit messages here
git push origin [BRANCH NAME] Pushes branch to the remote
General steps to make edits and push to GitHub
1. Clone the repository you wish to work on, and place it in a good location
2. Change your directory to where you wish to work
3. git branch [BRANCH NAME]
4. git checkout [BRANCH NAME]
5. Start working on files you wish to edit
6. Use git status to check that the edits are being documented
7. git add [PATH OF FILE(S) LOCATION] in order to stage the changes
8. git commit -m "[MESSAGE ABOUT CHANGES]"
9. git push origin [BRANCH NAME]
10. Submit a pull request physically in GitHub

For a downloadable version of this cheat sheet, navigate to this link.

Additional Resources

There are hundreds of Git resources available online. If you get stuck, do some targeted Googling. If you still can’t find what you’re looking for, ask your labmates in #tech.