We use Github Enterprise (licensed by Georgia Tech.) for version control of source code, documentation and occasionally useful (small) data files.

This tutorial currently presumes use of a Linux OS (eg. Ubuntu 16.04) and will guide you through:

1. Generating ssh keys & registering them with GT's GitHub Enterprise service
2. Navigating Git 'organizations' and 'repositories' accessible to you
3. Basic commands to clone repositories, pull changed files as well as commit and push your own changes

We prefer that you clone any git repositories via the SSH protocol. This requires you to:

1. generate an ssh public-private encryption key pair for each machine on which you want to clone a repository
2. register your public encryption key with GitHub Enterprise via their browser interface

1. Generate SSH Encryption Key(s):

For each machine on which you want to clone a repository and work with Git version control, you will need to generate an SSH encryption public-private key pair and register the public key with your GitHub Enterprise account.

On the machine (on which you want to clone Git repositories), open a terminal (here we use the Bash shell) and run the following command,

cd ~/.ssh

Note that if the '.ssh/' directory does not exist (eg. using a newly created username/account on the machine), you'll have to create it:

mkdir ~/.ssh
cd ~/.ssh

Now generate your SSH encryption public-private key pair,

ssh-keygen -t rsa -b 4096

It will prompt you for a file name in which to save the generated encryption keys,

Enter file in which to save the key (/home/achang/.ssh/id_rsa): 

As it's possible to have multiple encryption keys for different GitHub services (eg. other than GT's license GitHub Enterprise), you may want to name the file something that identifies it with GT's licensed GitHub Enterprise (eg. 'gatech_github').

Next, you'll be prompted to enter a passphrase/password. Remember your passphrase! When using Git commands that require access to the remote server, you'll be prompted to enter your passphrase.

Enter passphrase (empty for no passphrase):  
Enter same passphrase again: 

Upon completing this, run ls ~/.ssh in the terminal. You should see a pair of files listed with the file name specified earlier; one has the extension .pub (indicating it is the public key) while the other has no extension (and is your private encryption key).

Run, cat <filename>.pub, where <filename> is replaced with the file name you specified for your encryption keys. Copy the output of this command to a text editor. You'll need it in a moment.

Finally, we'll add the private key to the list of encryption keys that the SSH daemon uses,

ssh-add <filename>

Again, replace <filename> with the file name you specified for your encryption keys. Note that you are adding the private key (ie. the filename without the .pub extension).

An example sequence of commands and the expected terminal output is illustrated,

2. Register SSH Encryption Public Key:

Now that we've generated an SSH public-private encryption key-pair, we need to let GitHub Enterprise know the public key and that it is associated to your account.

In a web browser, go to https://github.gatech.edu. Login using your GT username and password. At the welcome screen/dashboard page, click on the 'identicon' (5×5 pixelated image created from a hash unique to your account) in the upper right. Click 'Settings' from the drop down menu,

Under 'Personal Settings', on the left-hand side, select 'SSH and GPG keys'. Then press the 'New SSH key' button in the top right,

Here, we'll add the public encryption key you previously generated from the terminal,

In the 'Title' field, enter a name for this key. The name should be something indicative of the machine on which this encryption key was generated. You may want to access GT's GitHub Enterprise from multiple machines; each machine will need to have an SSH public encryption key registered here. To distinguish which key belongs to which machine, a suggestion is to include the machine's 'hostname' in the name assigned in the 'Title' field (eg. 'smokescreen_ivalab').

In the 'Key' field, paste the public key contents you previously copied from the command cat <filename>.pub. If you are unsure what text to copy, example text (to copy) is highlighted in the prior image of the Linux terminal. Note that text to be copied will begin with 'ssh-rsa '.

Version-controlled files are organized into repositories maintained on GitHub Enterprise. An individual repository may contain all code, documentation and some data files associated with a single project. Furthermore, several commonly-themed repositories may be organized into a single git 'Organization'.

Any Git Organization accessible to you will be display in a drop down menu when you click on your account name (top left) on the welcome/dashboard page.

As an example, the IVALab has created an 'ivaMatlibs' Organization which contains several repositories housing commonly used Matlab code/libraries/utilities. Clicking on the Organization, from the drop down menu, then brings us to the Organization page, where all contained repositories are listed on the right-hand side, under 'Repositories'.

We can select a repository from this list, 'groups', for example. This brings us the 'groups' Git repository web page. We can manage the repository from here as well as grab its SSH URL to later clone the repository onto a local machine,

Here we present an example walk through in which we will clone a repository, 'rubbleTracker', onto our machine.

From the 'Snakey' Organization web page, we select the 'rubbleTracker' repository from the 'Repositories' list on the right-hand side. This brings us to the 'rubbleTracker' Git repository page,

Select 'Clone or download' to reveal the repository's URL. If the box that pops up is titled 'Clone with HTML', select the 'Use SSH' link on the top right of that box. We prefer all repositories be cloned via SSH and not HTML. The pop-up box should be titled, 'Clone with SSH'. Copy the URL in the text box (hint: begins with 'git@github.gatech.edu: ' and contains the repository name).

Next, open a terminal. Create a directory, in your /home area, within which you'd like clone and work on Git repositories. For the sake of this example, we'll name this directory 'gt_git/'.

cd 
mkdir gt_git

Next, create a directory for the Git Organization in which the repository resides. In this case, the 'rubbleTracker' repo resides within the 'Snakey' Organization.

cd ~/gt_git
mkdir Snakey
cd Snakey/

Now clone the repository,

git clone git@github.gatech.edu:Snakey/rubbleTracker.git

A snapshot of expected terminal output is illustrated,

Let's a add a new file to our repository!

cd ~/gt_git/Snakey/rubbleTracker
touch my_new_file.txt
ls

A new file named 'my_new_file.txt' has been added in the directory, '~/gt_git/Snakey/rubbleTracker'.

The following command will inform you of whether changes have been made to your local (version of the) repository, causing it to be out of sync with the remote repository.

git status

We first need to inform Git of any new files that it must track on our local machine.

git add my_new_file.txt 

Now that the file is tracked, we can 'commit' it to be staged for the next push to the remote repository.

git commit -m "added new example text file"

The '-m' flag allows you to specify text describing the changes being committed. You should ALWAYS do this!

Finally, we can push the staged changes to the remote repository,

git push origin master

Expected terminal output,

We previously added an empty file, 'my_new_file.txt', to the repository.

Now let's modify it and update the changes to the remote repository!

cd ~/gt_git/Snakey/rubbleTracker
echo "Hello World!" >> my_new_file.txt
cat my_new_file.txt

The commands above were a quick way to add simple text to our previously empty file. It now contains the text 'Hello World!'.

If we run git status, we see that Git is tracking the 'my_new_file.txt' and acknowledges there has been a modification to the file.

Commit the changed file so that it can be uploaded to the remote server,

git commit -am "added some example text"

The '-a' flag specifies to automatically add any files currently tracked by git (that have been modified) to be staged for upload to the remote repo. The '-m' flag allows the user to enter descriptive text briefly describing the changes.

Now push the staged changes to the remote repository,

git push origin master

Example terminal output is illustrated,

We additionally, see that the new file has been added via the repository's browser page,

In our final example walk through, we'll remove the text file we created from the repository and propagate this update/deletion to the remote repository.

cd ~/gt_git/Snakey/rubbleTracker
git rm my_new_file.txt 

git rm will remove a file both from the local file system as well as from the list of files that git tracks for changes. Running git status will show that git has marked this file for deletion.

Commit the change (ie. file deletion) to be staged for upload to the remote rpo.

git commit -m "removed example file"

Push the change,

git push origin master

Example terminal output is illustrated,