#Gitlab Part 2: git howto

So now that we have covered the setup with Gitlab, let's discuss how to start leveraging version control to back up and track your projects.

Some background on git

Git was created by Linus Torvalds to manage the development of the Linux OS kernel, one of the great open source projects of all time. So it is well suited to handle large projects with many different contributors.

You can think of a git repository as a chronicle of the entire history of a project. At any point you can leaf through the pages to revisit a previous version of your code and data. So git not only allows you to back up your data on a remote server, but also enables you to locally access your revision history. And it's fast, too.

Creating snapshots with git

Understanding the paradigm of the different states of a git repository is central to one's ability to practically use git. I'll refer to the figure below (modified from here) while attempting to define the terminology.

Your Working Directory is the directory where your project lives -- and it's where you ran git init or git clone to initialize a git repository (i.e. the ".git" hidden file is located there, which you can see if you run "ls -a" on the command line). When you Make changes to files in your working directory (adding files or modifying existing files), git keeps track of this: if you initialize a file called "new_file.txt" and then run git status, you'll see the following output:

bash-3.2$ git status  
On branch master

Initial commit

Untracked files:  
  (use "git add <file>..." to include in what will be committed)


nothing added to commit but untracked files present (use "git add" to track)  

Git noticed that this file is untracked, meaning that it is not included in the current snapshot of your project. In order to start tracking it, you can run git add new_file.txt to place it in the Staging Area. The staging area is a file which lists all of the files that will be present in your next snapshot.

Once you've added all the files to the staging area that you want to track, it's time to "commit" all of these to your next snapshot by running git commit. Everytime you make a commit, git will ask you to provide a message which describes the changes you made, which can be helpful when you want to go back and look at previous changes. You can enter a message interactively (git will fire up a text editor, normally vim), or you can specify a message directly by running git commit -m "Your message here".

Now your files are committed, great! Let's now describe the backwards arrow in the diagram, checking out previous snapshots in your version history.

Checking out previous snapshots

Let's say we repeat the steps above and add a second file: We create a file "second_file.txt", run git add second_file.txt, and then git commit -m "Created second_file.txt". Now you have two snapshots. But what if you want to go back to the first one?

What do these "snapshots" really look like, and how can you see them? To do this, just run git log:

bash-3.2$ git log  
commit 27b1da18fab93dc67b92c34ba062af20adedc808  
Author: Nima Emami <my.email@address.com>  
Date:   Sat Jul 9 21:47:49 2016 -0700

    Created second_file.txt

commit 824c3cf086e08f87bcbdf4ec2a1f30ef0ac62043  
Author: Nima Emami <my.email@address.com>  
Date:   Sat Jul 9 21:46:23 2016 -0700

    Created new_file.txt

From top to bottom, it lists your most recent to least recent snapshots. You can see our initial commit in the bottom block, with comment "Created new_file.txt", and our more recent commit above it. The long alphanumeric string listed above each commit is the SHA-1 hash string. Basically this is a unique string that corresponds to each snapshot, and it functions as the ID that you can use to "check out" different snapshots.

For example, your most recent commit contains two files.

bash-3.2$ ls  
new_file.txt    second_file.txt  

If you wanted to revert to the previous version, you can run git checkout 27b1da18fab93dc67b92c34ba062af20adedc808, where the long string is the SHA-1 hash for your first commit. Then, run ls again:

bash-3.2$ git checkout 824c3cf086e08f87bcbdf4ec2a1f30ef0ac62043  
Note: checking out '824c3cf086e08f87bcbdf4ec2a1f30ef0ac62043'.  
HEAD is now at 824c3cf... Created new_file.txt

bash-3.2$ ls  

So what happened to second_file.txt? Was it deleted? No it wasn't, it is still present. You can run git checkout with the most recent commit's SHA-1 hash to see it, or just run git checkout master -- master is a pointer to the most recent commit (on the current branch, but branches are beyond the scope of this basic lesson).

Pretty cool, no? If everything above makes sense then you've got your git basics down and are well on your way.


For additional lessons on the topic above, I recommend looking through Chapter 2 the git documentation, which in general is really superb.

For more advanced content, I recommend moving on to Chapter 3 to learn about branches.

Furthermore, if you would like a nice GUI to visualize your revision history (instead of using git log), you should download gitk. Instructions for downloading gitk for OS X are here, and may require that you install homebrew first. Once you have it installed, just run "gitk" on the command line and a nice window should pop up!