Git Tutorial

[M Charles]

Contents

1. Introduction
   
   • 1.1 What is Git?
   • 1.2 Various Resources
   • 1.3 Interface
   • 1.4 Installing Git
   • 1.5 Basic Setup
2. Our Git Server
   
   • 2.1 Accessing Repositories
   • 2.2 Getting an Account
   • 2.3 Basic Setup
   • 2.4 File Transfer
   • 2.5 Creating a New Project
   • 2.6 Using the Web Interface
3. Basic Commands
   
   • 3.1 Getting a Copy (git clone)
   • 3.2 Viewing State (git status)
   • 3.3 Syncing with Remote (git pull)
   • 3.4 Changing Code (git add, commit, push)
   • 3.5 Dealing with Conflicts
4. Anything Else (Optional)
   
   • 4.1 Branching

[M Charles]

1. Introduction

1.1 What is Git?
Just some basic information. Git is a version control system. This means that it allows you to keep a history of revisions, share files, backup to a remote, and more. It is also distributed (unlike CVS or Subversion), which makes it faster, more fault-tolerant, and more flexible.

1.2 Various Resources
Before going into the full details, I would like to point out some of the available resources about Git. These will most likely explain things in better detail than I can, so it is recommended to at least skim through one of them.

• https://www.atlassian.com/git/tutorial - A nice tutorial with nice diagrams
• http://git-scm.com/documentation - A bit long, but the official resource
• http://ndpsoftware.com/git-cheatsheet.html - An interactive cheat sheet

Also, sites like StackOverflow are your friend. There are probably hundreds of questions related to Git, so if you have a question about something, most likely there is already an answer available.

1.3 Interface
My main development platform is my Mac through the Terminal. So, all my explanations will use the corresponding Unix commands (which should work on Linux distros, Cygwin, and Unix environments for Windows). In the case that you need a GUI, check out http://git-scm.com/downloads/guis.

1.4 Installing Git
If you want to use Git on your local machine, you will need to install it. The following provides instructions for a couple OS's.

• Ubuntu - This uses APT. The first command is optional (it gets the most recent version for old distros, e.g. Ubuntu 12.04)
  

  Code: Select all

  add-apt-repository ppa:git-core/ppa
apt-get update
apt-get install git

• Windows - Here are two installation methods
  
  1. http://msysgit.github.io/ - This is the easier method. This provides Git, a Unix shell, a GUI, etc.
  2. http://git-scm.com/ - This is the light-weight method. Only downloads Git.
• Mac - Probably depends on how you are dealing with packages. That is,
  
  1. If you use a Windows-style approach, go download from http://git-scm.com/.
  2. If you use a Linux-style approach, download from your package manager (e.g. Homebrew, MacPorts). For example, using Homebrew,
     

     Code: Select all

     brew update
brew install git

1.5 Basic Setup
After installation, you will need to add some information to your .gitconfig file on every machine you use. In the following commands, remember to substitute with your own information:

Code: Select all

git config --global user.name "<your-name>"
git config --global user.email "<your-email>"

Also, if you are using Git 2.0 (you can tell by typing git --version), you also need to set the default push. You can look this up, or simply use:

Code: Select all

git config --global push.default matching

[M Charles]

2. Our Git Server

2.1 Accessing Repositories
I have set up the open-source Git management software GitLab on the server, which can be accessed at http://smlg.fiu.edu/gitlab. Clicking the link will most likely bring up a login screen.

2.2 Getting an Account
In order to login, a GitLab administrator will need to set up a username and temporary password. This account should be linked to the email and name that was typed in section 1.5. Dr. Yoo and I may try to set up an account for everyone who needs one. If you need a login or have difficulties accessing your account or want to change some of the admin-level user information, then you may want to get in touch through email.

2.3 Basic Setup
Once you are provided with a username and password, log in and change the password to something you can remember. Since SMTP through the server does not work, you will not be able to use "Forgot your password?". If you do need to reset your password, you will need to request a reset from an admin (e.g. Dr. Yoo).

Once you are inside your account, you may want to add an SSH RSA key-pair to make use of SSH file transfers. In the case that you already have a key-pair, then just skip the generation step. If you are on Windows, you may need to do something more (try googling "ssh-keygen windows").

Code: Select all

ssh-keygen
cat ~/.ssh/id_rsa.pub

In the first command, you can either just click <ENTER> for everything (you can change details if you want also). After the second command, copy all the output and then go to Profile Settings > SSH > Add SSH Key through the GitLab interface.

2.4 File Transfer
Communication with the remote server is done through either SSH or HTTP. I would recommend using SSH since HTTP has a limitation on memory and requires more resources.

If you want to use HTTP, you may need to run the command

Code: Select all

git config --global http.postBuffer 524288000

which should allow you to transfer larger amounts of data.

Either way, the location of the project through HTTP and SSH is shown after clicking on the project inside GitLab. For subsequent sections, I will use the syntax for SSH communication.

2.5 Creating a New Project
One of the main uses for the GitLab interface is to create a new project on the server. This can be done at the first page of GitLab after logging in. Click on the + New Project and fill out the page that comes up. After clicking Create Project, you should see instructions on how to perform your first commit.

2.6 Using the Web Interface
The web interface also provides some tools to help you get used to using Git. For example, after clicking on a project, you can directly browse the code (both current and previous versions) through the Files tab. There are many other capabilities available like viewing differences between versions and adding a Wiki.

[M Charles]

3. Basic Commands
For the following commands, let us assume the user user put a project foo.git onto the server.

3.1 Getting a Copy (git clone)
Given that this repository already exists, a local copy (clone) can be created by

Code: Select all

git clone git@smlg.fiu.edu:user/foo.git

The project should end up being created at the current directory. For the subsequent command, make sure you are inside the project (i.e. cd foo.git).

3.2 Viewing State (git status)
At any point in time, you can see the state of the code (i.e. changes you made, what is to be committed, etc.) by the command

Code: Select all

git status

Do this routinely to know what you need to add to the repository.

3.3 Syncing with Remote (git pull)
In order to get the newest code from the repository, you will need to "pull" the code down by the command

Code: Select all

git pull [<remote>] [<branch>]

In many cases, your remote and branch should be identical to what was used when cloning the code. In this case, you can drop the latter two arguments and do

Code: Select all

git pull

3.4 Changing Code (git add, commit, push)
There are three steps to adding to the remote repository.

1. Pick which files in your working directory you want to record as a "version"
   

   Code: Select all

   git add <filename>

2. Create the actual record so that the history is updated on your local machine
   

   Code: Select all

   git commit -m "<Message>"

3. Send the updated history to the remote (like pull, the arguments are optional)
   

   Code: Select all

   git push [<remote>] [<branch>]

3.5 Dealing with Conflicts
Since multiple people may be editing the same file, there are times you will run into conflicts and other issues. Always make sure to read any errors/warnings git tells you.

The most common issue would be a conflict. Git tries to perform automatic merging whenever possible, but if there are too many differences, it will give you a message saying that it failed due to CONFLICT in files X, Y, ...

At this point, you need to fix the conflicts. If you open the file X, you will see where the conflict is, which looks like:
<<<<<<<<<
version1
=========
version2
>>>>>>>>>

Delete the annotations (<<, ==, >>) and manually merge content in version1 and version2. Please go through other online resources to help you perform a manual merge.

[M Charles]

4. Anything Else (Optional)
4.1 Branching
Perhaps one of the most powerful features of Git is its branching. Unlike CVS/SVN, branching is fast and typically recommended in a standard workflow. Branching allows you to store your (potentially unstable) code without affecting the main code. For example, one can imagine having the main releases, a branch for "Release Candidates", a branch for a "Beta" version, and a branch for an "Alpha" version.

Another advantage of branches is that you can push your branch onto the remote repository. This means that if you are having difficulty with something (e.g. merging your changes back into the main code), you can let someone else deal with it.

You can create a local branch by

Code: Select all

git checkout -b <branch-name>

You can then move to another branch (e.g. master) by

Code: Select all

git checkout master

If you want your branch on the remote (assuming the remote is called origin), you can checkout that branch, add+commit files, and then do

Code: Select all

git push -u origin <branch-name>

In the case you want to move code from <branch-name> to master, you can do

Code: Select all

git checkout master
git merge <branch-name>

Finally, you can delete your branch (both remote and local) by

Code: Select all

git push origin --delete <branch-name>
git branch -d <branch-name>

[cwyoo]

I suggest we give git account with the same login id as the server login id. Assign random password and let the user change it as they wish.

[Kaumudi]

Dear Dr. Yoo,
Can I please get access to our Git server?
Thanks so much!
Kaumudi