Github, TortoiseGit, and Organizational Workflow Tutorial

This is a very rough, cut and dry introduction to using Github with the TortoiseGit Windows client in an organizational environment. Git itself can be a very convoluted (but featureful) tool; it's got quite a learning curve. The goal of this article is to get you up and running with a minimum amount of overhead. There's a massive amount of functionality it won't cover, and I encourage you to explore some of the more in-depth features of git -- there's a useful tool or trick for pretty much everything you can think of.

I apologize ahead of time for mixing terms around a bit. I tend to mash canonical and non-canonical names for things in a haphazard attempt to make explanations more clear, but rarely succeed in the attempt.

Before you start

You'll need to do the following things:

• Install msysgit, the Windows version of Git (installation instructions)
• Install TortoiseGit, a friendly GUI wrapper around msysgit (installation instructions)
• Have a Github account set up with the public half of your private key (setup instructions)
• Your, uhh, private key and passphrase

A brief overview of git and github

Git is a decentralized version control system. The "decentralized" bit sets it apart from other version control systems like CVS, SVN or Perforce. "Decentralized" means that there is no central repository -- each developer has a repository (or a few copies) that contains the entire history of everything. This has some advantages:

• You can make commits without being network-connected
• You can commit without worrying about build-breakage
• In a disaster scenario, you're fine unless every copy of the repo is wiped out

Unfortunately, these come at the cost of additional complexity.

To simplify things a bit, in most real-world scenarios, one repository is designated as blessed. This blessed repository serves as a central, true copy. All the other repositories (or, "clones") still contain the same version history; the blessed repository simply serves as a synchronization primitive to make the workflow cleaner.

You can do a variety of things with a repository. These include --

• Add new commits to a local repository (on your machine)
• Send commits to another repository (on your machine or the network)
• Get commits from another repository (on your machine or the network)

In the setup we're using, each developer interacts with three repositories:

• The repository on your local machine
• Your "fork" on Github
• The "one true repo", which is the central, blessed repository

You're free to do whatever you want with the repository on your machine and your fork on Github. Typically, you'll make commits on your local repository and send them to your Github fork immediately (or, as soon as you're network-connected). Commits going into the blessed repository must go through a review process (using Github's wonderful interface) before they're accepted and merged into the codebase. This process is performed using a pull request on Github, which is detailed further down.

But enough talk, have at you.

Let's get forking

Right now, we've only got the blessed repository. We need to create both your fork and your local copy set up. First, log into Github, navigate to our Github page and select a repository you'd like to work on. I'm going to assume for this case you want to work on edu-games (and, if that's the case, you can jump straight to that project).

Click the Fork button in the right-hand corner:

After some hardcore forking action, you'll be greeted with your Github fork. This is your personal copy of the blessed repository ("the upstream repository"; though you'll have to manually pull changes from upstream to get updates. We'll get to that later).

Assuming your Github username is Bob and the name of the upstream repository is edu-games, your fork will be located at https://github.com/Bob/edu-games.

Cloning your fork into a local repository

Git doesn't allow you to commit directly to a repository on the network -- you need to make a local copy before you can start doing work. Making a copy, in Git terminology, is called "cloning", and we're going to do it with TortoiseGit. Start by right-clicking on the Desktop (or other appropriate place) to bring up a context menu.

From this menu, select Git Clone... and you'll be greeted with the following dialog:

Here, you'll need to enter the URL for your Github fork, and the location of your private key. Do not enter the URL of the blessed, upstream repository (you won't be able to send your commits directly to the upstream). Once you've got the appropriate information inputted, click OK, and it will prompt you for your key's passphrase.

Toss in your passphrase and hit OK. TortoiseGit will save your passphrase for an indeterminate amount of time (either until Logout or Shutdown, I'm not entirely sure).

If this is your first time connecting to Github's servers, you'll get the following message:

Check to make sure that the rsa2 key fingerprint the dialog tells you is the same as in the screenshot; if it's not, then something is terribly wrong (it's not Github you're communicating with). The reason you get this dialog is due to the nature of public key cryptography. You don't yet have Github's public key, so you need to verify it with someone else (e.g., this tutorial). Once you connect once, their public key is saved on your machine and you'll never be prompted again. If their public key changes for some reason (e.g., because it's someone else on the other end of the tube), you'll know immediately and Git will cease communication before any damage is done.

If the key fingerprint is correct, click Yes. If not, phone your IT point-of-contact immediately.

A window should pop up with a progress bar as the repository is copied to your machine. Since it contains the entire history (and there are a lot of art assets and every version of them and so forth) it can take a bit of time on a slow network connection. It's only worth one coffee break though, since you only have to download everything when you first clone a repository.

Once it's finished downloading, we need to take one last step -- we need to tell your local repository about the blessed upstream repository. To start, open up the TortoiseGit settings by right-clicking in your repository and selecting Settings

Select Remote from the left menu. You'll get this dialog, albiet without the details filled in:

In the fields, put in

• Remote: upstream
• Url: The URL to the upstream repository, except with https:// replaced with git@
• Putty Key: Your private key

Hit Add New, then OK. You're all set!

Making changes, adding commits

With your fresh clone, look around, make some changes. Add a file or something. Or get some actual work done; not a big deal what happens.

I would like to note here that I'm going to skim over a lot of juicy Git functionality and internal workings here and just demonstrate some of the more fundamental workflows. Additionally, I'm not at all familiar with TortoiseGit, so the sequence of buttons that I tell you to press may not be optimal -- there may be features that combine multiply steps (e.g., for the command-line inclined, git commit -a instead of git add -A ; git commit (ignore that they have slightly different semantics)). Please fiddle with the interface; I'm sure it's filled with gems of some sort.

When you've changed something, go to the main folder of your repository and open up the right-click context menu. From that menu, select Add...

You'll get the above dialog telling you which files have been added, removed or changed. Make sure they're all checked and hit OK. Do note that adding files does not commit them. You need to do that in a separate step.

Once you've clicked OK, you'll get this:

To hit the previous point home, this dialog gives you a helpful Commit... button to commit the files you've added/changed/removed. If you don't hit commit, you can select Commit from the right-click context menu at a later point in time. For now though, hit Commit... to arrive at this dialog:

At this point, write a quick blurb about the changes you've made. The first line of your message should be no longer than 80 characters (basically, fit it in the one line of that text box). Each paragraph should be separated by exactly one blank line. It's not the end of the world if you break these conventions; however, the commit message may look funny in some tools if you do.

Don't worry about all the checkboxes, bells, and whistles for now (though they expose quite a bit of functionality and are fun to play with!). The defaults are usually what you want.

Hit OK to finalize your commit.

You should now be at this dialog (so many dialogs! I'm sorry; this is probably the most verbose way of doing things with TortoiseGit):

At this point, we've made a commit on our local repository. We want to send that commit up to our fork; this action is called "Pushing". TortoiseGit gives us a helpful button to push our new commit to our fork. Click Push.

As usual, the defaults are probably what you want here. Make sure that Remote is set to origin, not upstream, then click OK.

Once your commit is pushed to your Github fork, you can peek at your Github page with your browser to see the changes you've made. Note that they haven't been submitted for review for inclusion into the upstream repository. They're just on your fork.

Getting changes into the upstream repository

You've made changes to your Github fork, but you need to get them into the upstream repository for everyone else to have access to them. This is done by sending a pull request on the Github web interface. Log into your account and navigate to your fork's page. In the upper right-hand corner, there's a Pull Request button.

Click the Pull Request button and you'll be taken to the pull request page.

Throw in a title and a description for the pull request, then hit Submit. We will be sent emails and will have a chance to add comments to your changes.

An important note is that any commits you send to your fork before the pull request is accepted will be merged into that pull request. This lets you make any changes in response to comments, but can be a bit of a surprise if you don't know about it ahead of time.

When the pull request is accepted, you'll be notified by email.

Getting upstream changes back into your copy

As all of this is going on, we'll be making changes and sending pull requests. To migrate those changes into your codebase, you'll need to use a Pull command. From the right-click context menu, select Pull.

In the dialog that pops up, select upstream as the remote. If you don't have an upstream option, scroll up to the cloning section of this tutorial; it describes how to configure your remotes properly.

Then just hit OK and any changes made by other people will be pulled into your local repository. They'll be sent to your Github fork when you next push to it.

Conclusion

This concludes the brief introduction to basic git usage. There's a massive amount of functionality and things I've skipped over. Unfortunately, most of the git tutorials online focus on the command-line interface rather than using TortoiseGit exclusively. I actually can't find any good, comprehensive TortoiseGit tutorials, but when I do I'll add them here.