Using Git

Git is a distributed version control system (DVCS), providing speed and power for individual users while providing flexibility for groups to choose how they want to collaborate.

Setup

The first step is to download and install Git:

You can also visit the official download page at http://git-scm.com/download for additional options and platforms. Once we've confirmed that Git has been installed, we'll let it know who we are, and confirm that our settings have been saved:

There are additional Git environment variables we could set, but this will be sufficient. These settings are stored in ~/.gitconfig, which you can edit manually.

Clone an Existing Repository

Git is a distributed version control system, so to start working with an existing repository, we must actually clone that repository into our local development environment.

Here we cloned using an HTTPS connection, but other protocols can be used. Git has its own protocol (communicating on port 9418), but probably the most common method is to use SSH - using SSH will save you from entering your username and password in certain circumstances.

Create a Repository

We can also simply create a local repository from scratch:

Note that we could have created our new repo in a directory that already contained files; we simply chose to start with an empty directory. It bears repeating that we're not somehow missing something just because we created our repository locally - we have the full power of Git available to us, right on our own machine. For people unaccustomed to working with distributed version control systems, this can take a while to absorb: for a given codebase, no Git repo is inherently more or less important than any other repo (in fact, the clone command is simply a combination of init and fetch).

Adding Files

We'll start by creating a file and adding it to our repo, and see what happens:

Notice that a.txt is no longer untracked - is has been added to the staging area (also called the index). Whenever we do add, edit, move or remove files in Git, these changes are not immediately committed to the repo, but exist only in the staging area, which enables us to pick and choose what exactly gets committed to our local Git repo, and when. The staging area also lets us easily revert any changes without ever having touched our repo.

We'll learn more about the staging area as we go, but for now, note that git status indicated that it hasn't yet been saved within our repository, which we can confirm by checking the commit log:

That looks scary, but it isn't surprising. As with other version control systems, we must explicitly commit any changes we wish to save:

At this point we can verify thet nothing is lingeirng in the staging area, and that a.txt has actually been committed:

git status told us what branch we're looking at, what the most recent commit was, and what files it sees that are 'untracked' - files and or directories that our Git repo is not yet aware of. Let's add a.txt (we'll actually use a shorthand that adds all new or modified files in the current directory (including subdirectories)):

Note that our entire commit has been marked with a globally unique identifier. We'll see later that this enables us to share our work with others, but for now we should note that this reflects a certain philosophy of version control that differs from Subversion and other file-based systems - that the state of any given file is unimportant; rather what matters is the state of the entire project at a particular point in time.

Let's review what has happened thus far, because if you don't understand how Git works, it will be hard for you to ever really use it effectively. When we first created a.txt, it was not part of our Git repo. Running git status told us this explicitly - Git saw it as an "untracked file". In order to add a.txt to out repo, we added it with git add. Running git status

Sharing Changes

Any version control system that only lets us work with our local repository will be of limited utility - what we'd really like is to be able to share our changes with other developers. In order for another developer to contribute to our project, the first thing they'll need to do is clone our repo. Ordinarily this would be done over a network, but for now we'll simply clone our repo into a different spot in our filesystem:

When we say that we clone the repository, we mean that quite literally - our new BETA clone of the original playground repo is (for the moment), identical to the original repo, with all of the same commit history. (The actual picture is a bit more complicated, in that we cloned a particular branch of the repo (the master, in this case), ignoring any other branches that might have existed in the original playground repo. We'll look into this more later, but for now we simplify things, and in any case, for the master branch, we have created a perfect clone.)

Because we cloned our new repo from the original repo at ~/playground, Git assumes that in the future we will want to fetch updates from that repo. Consequently, when we clone a repo, Git specifies the source as a remote repository with which we're connected - more specifically, Git marks it as the origin:

The -v flag we passed to the git remote command gives us a little more information (namely, the URL of the remote repo). An interesting thing to note here is that we can specify additional remote repos. This might seem strange, but in fact is quite common. For example, developer A and developer B may both be working with clones from a repository which everyone defines as the central team repo. There may be occasions where developer A and developer B would like to push and pull changes from one another, before sharing their collective changes with the rest of the team.

To collaborate, we can pull (that is, fetch and merge) each others' changes as they become available. To illustrate, let's start by adding a new file (b.txt) in the BETA/playground repo:

And now let's add another file (c.txt) in our original playground repo:

At this point, in order to establish a truly peer-to-peer relationship between our BETA/playground repo and the original playground repo from which BETA was cloned, we'll explicitly add BETA as a remote repo for the original playground repo:

git pull fetches any changes (since the last time we pulled) from a remote repo, and attempts to automatically merge those changes into our local repo. By default, git pull will look for a remote named 'origin', and will pull

a.txt is now in a conflicted state, and is marked up accordingly (similar to SVN):

Resolving Conflicts

Defining Workflow

The very nature of a centralized version control system such as SVN or Perforce encourages a certain workflow - how team members share code in order to create a single coherent release. With Git however, we must consciously choose our team workflow, because no Git repo is inherently more or less important than any other Git repo. The peer-to-peer workflow we've been using so far may be fine for a team of two, but will quickly become unwieldy as our team grows. Thus, a more typical workflow is to set up a hub-and-spoke relationship between developers and teams:

In this workflow, the hubs could be developer repos, but this is probably a bad idea - in order to share changes, the hub developer would have to pull changes from all of her other team members (and know when to do so), and then notify all the other developers that they should, in turn, pull her repo to pick up any changes.

Headless repos do not have local copies of the actual files, and therefore do not have a staging area. This enables developers to push changes from their local repo to the shared repo - changes which in turn can be picked up by the other team members.

Now we must hydrate our headless hub repo. (Note that we could have also done this with git clone --bare)

By convention, 'origin' points to the primary source from which we pull others' changes, and to which we push our changes to be pulled in by others. Thus, let's re-point the BETA repo's 'origin' to point to our new hub:

Removing Files

But back to work. Unfortunately, we accidentally committed our *.iws file, which contains user-specific IntelliJ project desktop settings, and we'd like to remove it from our Git repo - without deleting the file itself:

Just as we must explicitly commit any file additions or modifications, so we must commit our removal:

Changing Your Mind

Just Ignore It

To avoid this problem in the future, we need a way to tell Git to ignore any *.iws files it finds in this project, which we can do with a .gitignore file:

In vi (or whichever text editor you prefer) we can edit the file to add specific files or else filname patterns) which we would like our Git repository to ignore:

We save the file, and then add and commit it to our Git repo:

Reeling In The Years

Git provides a variety of options for searching through our commit log:

Simple Branching and Merging

We can create branches (for research projects, released versions, etc.) just as we can in any other source control system. Ordinarily, we are working within the trunk, labeled "master". We can create a new branch labeled "version-3" like so:

Simple Maintenance

Validate that our repo isn't messed up:

Clean up the repo:

REALLY clean up the repo (TODO: What's the difference??):

Git Internals

Using GitHub

GitHub (http://github.com) is probably the single largest contributing factor to the widespread adoption of Git. Beyond hosting repositories

Pull Requests

Forking a GitHub Repo

With Git, when we think of checkouts, updates, adds, removes, and commits, we think of these things relative to our own personal Git repo (which is often local, but doesn't need to be). And when we want to interact with the rest of the world, we think in terms of merging repositories. So, to get working on a project for the first time, you'll clone someone else's repository.

Now, when you're working as part of a team, your team may have some notion of a "central repository" in order to coordinate your work, but this will only be by convention - there is nothing inherent in Git that makes any repository more or less important than any other repository. Let that sink in a second, because it's big - in the world of Git, everyone has a complete repository with a complete history, and no repository is inherently more important than any other repository.