Version Control with Git


CodeBooks

Git is a version control system (VCS). Using a VCS makes restoration, documentation, differentiation, experimentation, synchronization, and collaboration (among other things) much easier. We'll go over each scenario separately.

Follow Along!

This tutorial will walk you though the basics of using a VCS, and use Git to demonstrate along the way. Feel free to download Git and follow along!

Restoration

The simplest use of version control is simply to track changes and restore an old version if a bug appears. In fact, this is the part of version control that you probably use already, even if it's just Project X - 1/19/16 v4 (or, heaven forbid, Copy of Copy of Copy of Project X). If you've date-stamped a file as a backup, good for you! You've taken the long and complicated path of version control. Eventually you'll probably end up deleting some really old versions - say, last year - because they're just taking up space. Fortunately, VCSs have your back! You can store any extreme number of versions of a whole project, and a VCS will manage them for you with no trouble.

In order to demonstrate this, we're first going to need to go over some basic Git terminology and setup. This will lead us into the versioning system.

Repositories

The first Git term we'll need is a repository. A repository is simply Git's way of saying "project", and all of the versioning that goes on behind it. To set up your first repository, you just need to make a folder, open up a shell in it and type git init. This will set up a new repository in the current folder. If you have shown hidden files, you'll see a .git folder appear. This is where Git stores all of its information.

If you are using Git Shell, you should see [master] in your shell prompt. Git is telling you that you are on the master branch, which we'll cover later.

Staging

Next, create a file in that folder. You can do this with something as advanced as Eclipse or as simple as Notepad or even the shell itself with touch my-file.txt. This will create a file named my-file.txt in the current folder.

If you are using Git Shell, you will see the prompt from before change to [master +1 ~0 -0]. The three numbers (in order) mean you have created one file, changed none, and deleted none. The red text means that your new file is unstaged.

Unstaged, you ask? That's another Git term. The stage is where Git stores all of the changes to your files in the short-term. Staging a file means telling Git to realize the file has changed, and to update its records accordingly.

The way you stage files is with the git add command. Add takes one or more files as arguments and stages those files, or you can use --all or -A to stage everything.

After staging your one file, the shell prompt should look like [master s+1 ~0 -0]. Green means the new file is staged. (If you change the file after staging it, the red text will return, but it will look like [master +1 ~0 -0 | +0 ~1 -0]. Notice that the unstaged 1 is by the tilda (~), which means you have one file changed rather than created.)

Commiting

The next step in the versioning process is to make a commit. A commit is a collection of changes saved with a description, a date and time, and an author. In the long way of version controlling, each folder is a commit - except there's no author or description! This is a benefit of Git and other VCSs: they will automatically fill in the author and date, so you only have to worry about the changes and description.

Now that you've created and staged your new file, you are ready to commit it. The command to commit (commit as a verb is short for "make a commit") is git commit. If you run the command with no arguments, it will open your default text editor to input a description. However, for simple messages, it is easier to simply supply the message in-line. To do this, you simply add a -m argument: git commit -m "<your message here, between the quotes>". Congratulations! You've made your first commit, and learned the power of versioning!

Restoration

Now that you've done everything right, it's time to do something wrong. Change the file you made earlier, and save the changes in a separate commit. We will treat this commit as a bad commit, so we can learn how to revert it. Reverting in Git is simply undoing a commit, and everything that happened after it.

The first thing we need to do is find out which commit we're going to revert. Commits have a fifth property, an SHA hash. This is a security term, but all that is relevant to this article is that the hash is a unique way to identify that commit.

In order to see the commit hash, you need to show the contents of the last commit. The command is git show -q. The -q flag is short for quiet, which just makes the output a lot smaller and easier to read. Here's a sample report for the latest commit on my website at the time of this writing:


        

The important part of this report is the first line, which tells us the commit's hash. It's the long jumble of letters and numbers after the word "commit". We can now copy that hash (you might need to right-click, click "Mark", select the text, and hit Enter) and pass it into git revert to undo that commit. If you open the file now, you should see what the file contained in the first commit. If so, congratulations on mastering the first skill of version control!

Documentation

Documentation is less common with manual version control. Documentation, in this case, means that you document what changed in this version of the project. You could include a short description in the folder name, or a readme/changelog file in the folder with a longer description. With Git, you can document your changes rather simply - and in fact, you already have. When you commited, you used the -m flag. This specifies the message for that commit, which is your documentation.

Differentiation

Say you walk away from your project for a couple days. Vacation happens, other projects happen, finals happen - whyever you walked away, you just can't remember what you were working on before you left. Well, Git is here to save the day! Using the git diff command, you can view all changes that were made since the last commit. You can also view what changed between two commits, a range of commits, and so much more - check out the official documentation for more info.

Git's diffs are intuitive to read, once you get the hang of them. Green lines, which start with a +, mean lines that you've added; red lines, starting with a -, mean deleted lines. Changed lines show up as one addition and one subtraction.

Experimentation

If you ever want to add a feature, but don't know if it'll work or be worth the effort, you obviously don't want to put this code in the same folder as your main project. If you need to add something else to the project, you don't want to have to include the half-finished unstable feature in your stable code!

Using manual version control, you may create a sub-folder called New Feature and only work on the feature there. That way, stable work could stay in the main project, and the unstable work would be separate. But then, if you finish the unstable feature, how do you integrate the unstable feature back into the stable code?

The VCS solution for this is called branching. You can take the current code and branch off,

Synchronization with Github

Using Git, and a code-storage/sharing site such as Github, you can to move all versions of your project across computers with ease. Github stores the full Git repository on its server, and you can use git to download (pull) from and upload (push) to their servers.

First of all, you will need to create a Github account to access their servers.