Git and GitHub

	This is a guide Welcome! This article is intended to guide you through an SSI process. While its authors have made efforts to make it useful, if you have questions, please ask the authors on Slack. They will be able to both help you and improve this resource for future SSI-ers. This article was written by Sasha Maldonado `@{{{display-name}}}` .

Git is a version control software that tracks changes made to software files and allows unsuccessful changes to be easily reverted. Projects in Git are stored as repositories, which are folders containing a list of files maintained by Git. GitHub is an online service that allows a team of users to easily work together on code, tracking who made which changes, allowing different users to pursue different solutions simultaneously, and helping all members of the team keep their local copies of shared code up to date. GitHub allows users to upload and download repositories, allowing team members to share new code they have written and to update their code to include their colleagues’ contributions.

Setting up Git and GitHub

Checking for Git

Git is built into most Unix-based operating systems (OS X and Linux). On a Unix system, find Terminal (on Mac, in Applications/Utilities) and type “git”. If a dialogue comes up saying that the command “git” is not found, you will need to download Git as described below. Otherwise proceed to “Setting Up Github.”

Downloading Git

On Windows systems and Unix systems that failed the test above, you will need to download a Git client. Go to the Git download page and pick out a download for your operating system. After downloading and installing Git, you should now have a program called Git Bash - this program is functionally equivalent to Terminal for all uses later in this document, and all of the commands described should have the same function in Git Bash as they do in Terminal.

Setting Up GitHub

Sign up for a free account on GitHub’s website. A recommended convention for usernames is your first initial followed by your last name. It is helpful for your username to resemble your real name so that people can easily tell who contributed what code so that they know who to contact with questions. After creating an account, you will need to be added to the SSI GitHub organization. GitHub does not currently have a feature to allow users to request to join organizations; to be invited, email or Slack message any member of the “Owners” group. The current lead GitHub administrator is Sasha Maldonado, @{{{display-name}}} .

Git Usage

Navigation

If you are familiar with basic shell commands (cd, ls), you can skip to the next section, which discusses more Git-specific commands. All commands are briefly summarized in a Cheat Sheet at the end of this document.

Git is run from the command line (Terminal/Git Bash), a text-based interface into which commands can be typed to perform actions. A default command line will look something like this, with “smaldonado” replaced with your username.

smaldonado:~ smaldonado$

The command line maintains a “pointer” to a specific folder in your file system, which is assumed as the reference for all file names typed into commands. When a new terminal (either Terminal or Git Bash) window is opened, the pointer will point to a default location denoted by a tilde, “~”.

smaldonado:~ smaldonado$ pwd /Users/smaldonado

The command pwd (“print working directory”) causes the console to print the current location of the pointer. In the example above, pwd is used to show the real location of the default “~” directory. Note that the example above is the location of the default directory on OS X and that it will be different on Windows and Linux operating systems. Your pointer’s current directory, relative to the default, will be shown in the first part of the command line after the colon (see below for an example).

To change the location of the pointer, the command cd (“change directory”) is used. Commands beginning with a “/” start from your computer’s root (lowest) directory, and are generally not necessary. All other cd commands are assumed to be relative to the pointer; for example, the command below moves the pointer to a folder called “GitHub” stored in the default directory.

smaldonado:~ smaldonado$ cd GitHub smaldonado:GitHub smaldonado$ pwd /Users/smaldonado/GitHub

When changing to a folder with a space in its name, you will need to “escape” the space by placing a “\” character in front of it. For example, to switch to a folder called “GitHub Projects,” you would need to type the folder name as shown below.

smaldonado:~ smaldonado$ cd GitHub\ Projects

The cd command also includes an autocomplete feature; by typing the first several letters of a folder name and then hitting TAB, the terminal will attempt to find a directory beginning with the letters typed in. This feature is good for filenames with spaces, as they will automatically be escaped.

The cd command can be used to move several levels down in one line. For example, the following is a valid command that moves the pointer to the folder “opt-comms” within “GitHub.”

smaldonado:~ smaldonado$ cd GitHub/opt-comms/

The “/” character within a file name shows that the text to the right of it is a subfolder. Ending a location with a “/” (as above) is optional and does not affect the command being run. You can also go up a subfolder level by using “../” in a file path. For example, to switch to a “rockets” folder also stored in “GitHub” from “opt-comms,” you would type the highlighted line below.

smaldonado:opt-comms smaldonado$ pwd /Users/smaldonado/GitHub/opt-comms smaldonado:opt-comms smaldonado$ cd ../rockets/ smaldonado:rockets smaldonado$ pwd /Users/smaldonado/GitHub/rockets

FInally, simply typing cd will take the pointer back to its default location. To help illustrate this, the following list of commands is provided. All listed commands perform the same function of moving the pointer back to the default location.

smaldonado:~ smaldonado$ cd smaldonado:~ smaldonado$ cd ~ smaldonado:~ smaldonado$ cd ~/ smaldonado:~ smaldonado$ cd /Users/smaldonado smaldonado:~ smaldonado$ cd /Users/smaldonado/

The command ls (“list”) shows the names of all files and folders stored in the folder the pointer is currently on. This is quite useful, and strings of cd and ls commands are common.

There are many other useful commands that can’t be covered here, and the discussions above are quite cursory. To get more detailed information about any command, use the man (“manual”) command, followed by the name of another command.

smaldonado:~ smaldonado$ man ls

The above line will display the manual page for the ls command; scroll through it using the arrow keys, and exit by hitting the “q” key. The language for manual pages takes a bit of getting used to, and for introductory purposes the internet may prove a better resource for learning the functions of commands. However, the manual page is the definitive reference for how to invoke all of the possible functions of a given command.

Configuring Git+GitHub on a Computer

Once you’ve completed all of the setup for both Git and GitHub, you can begin to download the SSI code. First, it is strongly recommended that you create a “git” folder in or close to your default directory. You can either do this through your computer’s file system or from the command line with the command mkdir ‘git’ (mkdir, “make directory”). cd to this directory (or wherever you would like to store local copies of SSI code).

SSI’s code is broken up into repositories based on project. All of the available SSI repositories (“repos”) are available on the SSI GitHub page. To download a repo, go to its page from the SSI main page and locate the “HTTPS Clone URL” and copy it to your clipboard (as shown in the right of the image below).

Then, in your terminal (in your designated GitHub directory), type:

git clone

Followed by a space and the URL you copied from GitHub. You may need to right click (as opposed to ctrl/cmd+v) in order to paste the URL. Hit enter, and you should begin to download the selected repository. Once it’s done, you have a local copy! You can repeat this process with other repositories as desired.

High Level Git and GitHub Overview

Git (with GitHub) contains four different “layers” to be aware of:

The Working Directory refers to a real folder stored on your computer containing real, editable files that you can add, delete, move, and change harmlessly.
The Index (AKA Staged Commit) holds snapshots of files before they are more permanently committed. The git add command takes snapshots of files in the working directory at the moment the command is run and puts those snapshots into the Index.
The Commits layer contains a record of snapshots made over the lifetime of a repository. The Commits begin with a snapshot of the first set of files added to the repository, and in each subsequent commit those files have been somehow modified; changed, added, deleted, moved, etc. Essentially, each commit is a saved state of the project folder, and any commit - or even individual files from a past commit - can be easily reverted to if it is determined that subsequent changes are undesired. The git commit command turns the contents of the Index into a new commit in the Commits layer.
The Remote layer functions much like the Commits layer, storing a lifelong history of commits synchronized across users and, in the case of the SSI GitHub, publicly viewable. This publicity means that anyone can keep up to date with the code put in the Remote layer, but only members of the SSI team can add their changes to the SSI Remote repository. The command git push adds all of the commits made locally since the last git push to the Remote layer.

One important Git concept that these four layers don’t communicate is branching. Git can track more than one lineage of changes to a set of files; each history of changes starting from a common commit is a branch. One of Git’s most powerful features is being able to merge divergent edits made to a repository - sometimes even to the same file - allowing individuals to simultaneously pursue different lines of edits and then combine their work into a single releasable set of files. This feature has insofar not been often used in SSI, but it is still important to mention. Every local instance of Git has a “working branch” that all of its commits are added to (by default, “master”), and when these commits are pushed to GitHub, they are added to an online branch with the name used by the local working branch. Without making changes to your Git installation, you will by default use the “master” branch, which is generally okay for SSI purposes. See Advanced SSI GitHub Usage for more on when and how to use branches.

Using Git Commands

Note: In the syntax examples below, the items in angle brackets (<>) are descriptions of what should be included in each command. Do not include the angle brackets.

All of the following commands (except git clone) must be run from your terminal while your working directory is the relevant repository folder (for example, “GitHub/opt-comms”). These commands all operate on only one repository at a time. git clone must be run from your desired GitHub folder, and will create a folder for the repository being cloned.

git clone is run once when first beginning to work with an online repository. git clone copies the most recent online commit into a new working directory and locally saves the commit history stored online. It also does the configuration needed to make git push and git pull work.

Syntax: git clone <https clone link>

git add adds snapshots of files currently in the working directory to the index. Subsequent changes will not be added to the index unless another git add command is run.

Syntax: git add <filename of file to be added> git add --all - adds all files changed, added, deleted, etc.

git status shows what files have been changed since the last locally stored commit and shows which of those changed files are in the index waiting to be committed. It is good practice to run this after the last git add before a git commit to make sure all of the correct files are being committed.

Syntax: git status

git commit takes all of the snapshots in the index and turns them into a local commit. It is very important to leave a message explaining what changes were made in each commit; a single sentence change summary is usually sufficient.

Syntax: git commit -m ‘<brief, descriptive commit message>’

git push takes all of the local commits that have been made since the last online commit and adds them to the online repository. In order for this to happen, the local commits must all follow from the last commit online. If this is not the case, git pull must be used to download the current online commits and reconcile their differences with the commits stored locally. git push can then be used again.

Syntax: git push
- when pushing normally to the “master” branch

git pull takes the most recent online commit and merges it with your most recent local commit, making your local files safe to push up to GitHub online. A good workflow for git push and git pull is as follows:

Before starting work on one or more code files, git pull to bring your local files up to sync with the latest code online.
Make changes to your code, periodically using git commit as you improve your code.
When done with an editing session, git push to put all of your commits online. This is important both for making use-ready code available to everyone who may need it and for allowing others to continue editing your code from where you left off.

Syntax: git pull
- when pulling normally

Terminal/GitHub Basic Command Cheat Sheet

Generic

cd <path>
- Change the current working directory for Terminal

pwd
- Show the absolute location of the current working directory

ls
- List all of the files within the current working directory

man <other command>
- Display the Unix Manual entry for any command

Git/GitHub Specific

git clone <https clone link>
- Copy an online repository into the current working directory, creating a new folder there for the repository’s local copy.

git add <filename of file to be added>
- Adds a specific changed file to the staging area for the next local commit.

git add --all
- Adds all files that have been changed, added, deleted, etc. locally since the last local commit to the stage for the next local commit.

git status
- Show all files that have been locally changed and whether or not their changed versions have been staged for the next local commit.

git commit -m ‘<brief, descriptive commit message>’
- Make a local record of changes in files added to the staging area.

git push
- Push all committed local changes to the online “master” branch.

git pull
- Retrieve all changes made to the online “master” branch since the last local commit and download them for local use.