Git

Git is a versatile distributed Source Code Management system (SCM), and unlike a centralized SCM (i.e Subversion), many different versioning workflows are possible. This page will describe the basics of using Git, the Gitlab service available at https://git.eecs.ku.edu, and as well as a couple of Git workflows recommended for EECS coursework.

Note: If you are already familiar with Git feel free to jump the section on Gitlab.

Fundamentally, Git is simply a tool that keeps track of changes made to files. A Git repository consists of a history of commits (each assigned a unique revision number). Each commit captures the state of tracked files at that time. A commit consists of the addition of new files to the repository, changes made to files already within the repository, and the removal of files from the repository. The power of using a repository is that you can return to any previously committed state allowing you to see how files have changed over time, and who has made those changes.

In it simplest form a Git repository tracks changes to files, but Git repositories really shine when used by multiple people working on the same project. This allows each developer to work within their own development space, commit finished features to a repository, and then easily share those changes with fellow developers. The next section will detail the EECS Department's Gitlab service which allows EECS user to share access to their

Basic Git Commands

This page will refer to several Git commands, a few are listed below for your convenience. If you are unfamiliar with Git and/or VCSs see the More Information section below.

git init - Creates a new Git repository.
git clone - Clones an existing repository.
git add - Adds a file to the list of staged files.
git commit - Commits staged files to the repository.
git status - Show a list of modified files and staged files.
git log - Outputs the (recent) commit history of the repository.

.git Directory

When the git init command it executed a .git directory is created within the current directory. This .git directory contain the Git repository. If the .git directory is deleted, than the Git repository is deleted.

More Information

The following sections will provides details on using Gitlab and how to setup several basic Git workflows on EECS systems, but is not a Git tutorial. If you are unfamiliar with Git and it's basic commands read the Git Basics chapter of the Git manual.

Gitlab

To facilitate the use of Git within the EECS Department a Gitlab service has been made available to all EECS users. Gitlab is a web-based system for managing Git repositories (similar to GitHub). If you are familiar with GitHub you should be comfortable with Gitlab and should be able to jump right in (https://git.eecs.ku.edu). For those of you who are not this section will provide a short tutorial on using Gitlab.

Note: This tutorial assumes you are working on an EECS Linux Workstation or one the the EECS Cycle Servers.

Initial Setup

First off, let's make sure you've initialized your EECS Gitlab account and made some necessary configurations. Open a browser and go to https://git.eecs.ku.edu and login with your EECS username and password (LDAP sign in). If it's your first time logging into Gitlab you will see a welcome message, a project limit, and a button to create a new project. Before we create a project let's first create an SSH key to associate with you Gitlab account.

SSH Keys

Gitlab uses SSH keys for authentication to allow you to make changes to your repositories (a.k.a. projects) without using a username and password. To add your public SSH key select the Profile option in the upper right-hand corner of the page and then click the Add Public Keys button.

To create an SSH key pair for use on EECS Linux Workstation and EECS Cycle Servers follow the instructions below:

Login to an EECS Linux Workstation or SSH into one of the EECS Cycle Servers.
Generate a public/private RSA key pair using the same email address that appears in your Gitlab profile:
```
ssh-keygen -t rsa -C "you@ku.edu"
```
Copy the contents of your public key:
```
cat ~/.ssh/id_rsa.pub
```
Paste the content of your public key file into the Key text area in Gitlab's Add an SSH Key form.

Creating a Project

Now that you have added your public SSH key to Gitlab, let's go ahead and create a new project by selecting the New Project icon in the upper right-hand corner of the page. Name the project whatever you would like.

On the next page you will see a bar with an SSH connection string and three sections of code. Let's look at the code sections first.

Git global setup: This section of code sets your local Git configuration, and will only need to be execute once on either an EECS Workstation or one of the EECS Cycle Servers.

Create Repository / Existing Git Repo: Here you can either associate your new Gitlab project with a new local repository or an existing local repository. For the purposes of this tutorial we'll create a new local repository. While logged into an EECS Workstation or one the EECS Cycle Servers execute the commands in the Create Repository section.

Congratulations, you have finished creating your first Gitlab project!

More Information

To find out more about Gitlab visit the help section at https://git.eecs.ku.edu/help.

Workflow Examples

This section will discuss three different Git workflows and how to set them up on EECS resources. Many other workflows are possible with Git and Gitlab and EECS users are free to use whatever workflow they would like.

Example 1: Solo Workflow

In the simplest case Gitlab can be used to track changes to project files as described in the first section. In fact, if you've followed the Gitlab tutorial above this is exactly what you've created. As you may have noticed there are actually two repositories in the graph to the left, one labeled Local and one labeled Remote.

Local Repositories: The local repositories are all that you really need with Git to track changes to files, and if you have no intention of sharing your code with others than it might be all that you really need. If you start with only a local repository you can always add it to Gitlab using the Existing Repository instructions for a new Gitlab project.

Remote Repository: While a local repository is all that you need to use Git, remote repositories allow you share code with others and take advantage of useful services, such as Gitlab. In the workflow to the left you can push your commits to your Gitlab remote repository using the git push command. Once you have done this you can take advantage of Gitlab's many feature's.

Example 2: Centralized Workflow

Let's say that you've been working on the project above and now have several colleague who are interested in collorating with you and you would like make this project available to them via Gitlab.

In this case, when you've finished some segment of code and you've committed it to your local repository, you can push it to your remote repository.
and 3. Now that you have pushed your commits to your remote, your colleague's can now pull those changes down to their local repositories for this project.

To grant other EECS users access to your remote repository add them as project members to your project. You can grant different levels of permissions to different people. For more information about Gitlab permission visit: https://git.eecs.ku.edu/help/permissions.

Once you have granted others permission to your remote repository (a.k.a Gitlab project) they can clone your remote repository to create a local repository to work from using the SSH connection string for that project.

Example 3: Distributed Workflow

The centralized workflow descibed above should be familiar to those of you that have worked with SVN in the past. How Git differs from a centralized SCM, such as SVN, is that it allows for de-centralized worklows, like the one depicted to the left. In this distributed workflow, both you and I have our own local and remote repositories for the project.

When you have completed some code that you have been working on, you commit and push it to your remote.
Then I pull your code down to my local so that I can start working with it. Say I notice a bug, fix it, and commit the fix. Instead of pushing that commit to your remote, I push it to my remote.
For you to get my bug fix, you will need to pull down my changes from my remote.

To setup the distributed workflow described above requires that you have multiple remotes associated with your local repository (one for yourself, and one for each other developer). For more information about setting up and managing remotes visit http://git-scm.com/book/en/Git-Basics-Working-with-Remotes.

More Information

Workflows: To find out more about Git workflows visit http://git-scm.com/book/en/Distributed-Git-Distributed-Workflows
Merging: When working with other on a project there is always the potential that changes made by one person conflict with the changes made by another, and the conflict needs to be resolved by merging the changes. Resolving merges is beyond the scope of this tutorial, but more information about this topic can be found at http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging.
Git Manual: The Git Manual referenced several times through out this tutorial is a excellent source of information about Git and can be located at http://git-scm.com/book.