====== 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 [[http://git-scm.com/book/en/Git-Basics| 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: <code>ssh-keygen -t rsa -C "you@ku.edu"</code>
  - Copy the contents of your public key: <code>cat ~/.ssh/id_rsa.pub</code>
  - 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 ======
<columns 100% 20%>
{{:solo_gitlab_workflow.png|}}
<newcolumn 80%>
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.
</columns>

===== Example 2: Centralized Workflow ======
<columns 100% 34%>
{{:centralized_gitlab_workflow.png|}}
<newcolumn 66%>
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.
</columns>

===== Example 3: Distributed Workflow ======
<columns 100% 34%>
{{:distributed_gitlab_workflow.png|}}
<newcolumn 66%>
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.
</columns>

===== 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.