Saturday, January 9, 2010

Getting started with Git

One of the toughest things to learn during this game project was actually our source control Git. Phil(our most experienced member) insisted we use Git because of its superiority to SVN and the like. Git allows you to create both a remote and local repository of your code. This means you can branch and merge code all you like on your local repository and only interact with the remote repository when you need to.

I've used SVN before so I didn't think much about learning Git. Ironically, after a week of trying to share code between the four programmers in our group, Phil was probably the least Git literate in our group. Git's cryptic interface can be pretty unforgiving, especially if you don't know Git's recommended workflow.

So I decided to write a guide to getting started with Git on Windows.

First you'll want to download and install Git here:

I downloaded the full installer. Once the installation is complete, you should have the options "Git Bash here" and "Git GUI here" in your right click menu. I created a directory to store the project code called "flashproject". Right clicking on this directory and clicking "Git Bash here" should start a command line pointing at this directory.

Get the code from the remote repository

If you've set up a remote git repository with GitHub, you'll need to create an SSH public key to identify yourself. Detailed instructions for creating this key can be found here.

Now, you need to get the code from the repository. If that repository is GitHub, we do it with a clone command:

git clone[repository creator's username]/[repository name].git

This should download all the code from the remote repository into the directory we created. You only need to clone once. After this first time, you'll use git pull to get code from the remote repository.

UPDATE: Well, after trying this out with people in person, it looks like Git won't navigate to the newly cloned directory. We couldn't work with the code through Git until we used cd DIRECTORYNAME to navigate Git into the working directory. You'll know when you're in the right directory when you see (master) in the Git command line.

The Git Workflow

Once you have all the files on your hard drive, it's time to write some code. Once you're done, you'll need to follow a workflow to make sure your changes and any changes pushed by other coders to the remote repository merge nicely.

1. Add any additional files to Git's tracking.

git add "File path and name."

2. Commit changes locally:

git commit -am "Commit message"

Here is the biggest difference between working with Git and SVN for me. You need to commit your changes to the local repository if you want to then push the changes to the remote repository. When me and Phil started using Git, we were confused when it refused to pull remote code because of conflicts. Can't we just merge those conflicts? Turns out Git won't merge your changes with any changes from the remote repository unless your local code is committed first.

UPDATE: -am will allow you to write the commit message in the command line. If you choose to type git commit -a the command line will open a text editor so you can write a very detailed message. If you have lots of complex changes, this method may be preferable to the -am shortcut as git automatically generates some change logs in the text. One thing I found confusing about the editor, however, was how you exit. Once you've typed your commit message, you'll need to press ESC on your keyboard to enter its "command mode." Then press shift and ZZ to tell the editor to exit.

3. Pull the changes from the remote repository.
Just to check if there have been any changes since you pulled/cloned last.

git pull

4. Merge the remote and local changes if there were any.
Git will automatically merge basic differences to code, but you'll need to resolve more complex differences. Git will go into merge mode and modify the files, showing your changes and the remote changes with markers. These markers should look something like this:

//Changes from one side.
//Changes made by the other side.

You'll have to go into each file and pick and choose which lines of code you want to keep manually. This seems complicated, but unless you and another coder are working on the exact same lines of code at the same time, you won't have to do manual merging very often.

5. Push your merged changes to the remote repository.

git push

This is just a basic start to pulling code from a remote repository, working with your local copy and pushing the changes back to the remote repository. Stay tuned for a guide to working with branches remotely and locally.

No comments: