Kleinsch

I’m in the process of writing a simple game engine for the iPhone and have been doing a lot of research about game engine design. I also looked into using a prebuilt iPhone game engine, but decided I’m more interested in writing it myself (because of technical, business, and hacker ego reasons). Here are some resources I found helpful.

Books
Game Engine Architecture – A textbook about game engine design, this presents options and tradeoffs for each piece of the engine. Light on actual coding, so you’ll have to be able to develop things yourself, but jam-packed with useful information. I found this invaluable while in the design stage.
Game Coding Complete – Walks through the process of building a game engine and using it to create a full-fledged game, complete with AI and multiplayer networking. Found it useful in tying the pieces together, but only presents one approach to most problems.

Presentations
Gamasutra has all the presentations from the Game Developers Conference from 2000-2003 (Use the links in the sidebar to navigate year).
Marcin Chady – Theory and Practice of Game Object Component Architecture – The best presentation I found about component driven game object design.
Alex Duran – Building Object Systems – Features, Tradeoffs, and Pitfalls
Scott Bilas – A Data-Driven Game Object System
Rob Fermier – Creating a Data Driven Engine: Case Study: The Age Of Mythology
Doug Church – Object Systems
Mick West – Refactoring Game Entities with Components
Kyle Wilson has a blog with a bunch of strong posts about engine design. Be sure to check out the old posts as well.

iPhone Engines
Unity 3D – Commercial 3D engine. Combines powerful scripting with a visual editor to dramatically speed up the development process. Hundreds of games on the App Store. Well laid out component model.
Oolong Engine – Open source 3D engine. Uses PowerVR POD for storing meshes and Bullet physics.
SIO2 – Open source 3D engine. Toolchain built around Blender and integrates with Bullet physics.
Cocos 2D – Open source 2D engine. Well organized.
Torque 2D – Commercial 2D engine
Torque 3D – Commercial 3D engine
Shiva 3D – Commercial 3D engine. Windows only editor, but supports iPhone publishing

Engines for other platforms
Unreal – One of the most successful game engines on the market. Worth reading through the documentation to pick up on design considerations. Separates out most game logic into a custom scripting language called UnrealScript.
Source – Valve’s engine for Half Life 2 and many mods. Extensive wiki documentation.
idTech 3 – Engine from Quake III Arena, now open sourced. A few years out of date, but shows a lot about client-server programming as well as insane performance optimizations. There are a couple people who have gone through the source and give pointers on things to look at, which is immensely helpful .
Panda3D – Open source engine written in Python and C++. All game logic is written in Python. Does a good job of showing how to separate engine code from script.
OGRE – Open source C++ engine in process of being ported to iPhone
Crystal Space – C++ open source engine

At any new job, there are a lot of things for engineers to learn. It’s easy to get distracted by platforms, languages, team characteristics, the industry, business models, etc. One area that gets frequently overlooked is learning your company’s core competency or technology. At every company (or department within a large company), there’s an area that’s their specialty. For Apple, it’s building intuitive products. For Oracle, it’s organizing huge amounts of data. While you can come out of a job and say that you grew your general software development skills, it’s better to do that and gain a new area of expertise.

Your company’s core strength may not be part of your job description. You may be working on back-end enterprise reporting for a company that prides itself on brilliant user interfaces or doing interface work for a company that specializes in data analysis. While you may not ever be directly working on the core competency, it’s still possible to learn enough to be useful later on. If it’s something that can be researched on your own, grab some books and do some reading. Talk to people who are working on it and get their opinions and ideas. Unless your company is highly secretive, you probably have source code access. Look into what tools are being used and read the source. You don’t necessary need to know it line by line, just enough that you understand the concepts involved and could participate in a discussion about pros and cons.

Obviously, if you’re working on web applications you should be very familiar with web programming. It’s going to be assumed in the future that you’re an expert in the language and platform on which you spent the most time. While it’s essential to learn these things, most companies’ core competency is not knowledge of a platform or language. 37signals aren’t focused on Ruby on Rails, they design simple, clean products. ngmoco don’t pride themselves on knowing iPhone APIs better than anyone else, they’re good at making fun mobile games. While learning the platform is essential, it’s important not to confuse that with learning the company’s core competency.

Being familiar with your company’s core competency enables you to be part of the important discussions that go on every day. When you don’t understand the key concepts involved, you’ll have a hard time participating in conversations about changing the core product. When you have the knowledge and can offer suggestions, you’ll get involved more and will be seen as more valuable to the company. If a key project needs another person, you’ll be much more likely to get on it. A developer with key domain knowledge is also much more difficult to replace, which can benefit you financially and in terms of job security.

Unless you’re staying focused to one specific industry, these things are usually fairly unique. In the first two jobs I’ve had out of college, I’ve learned all about call platforms (the software that manages automated phone calls), machine learning, and ad servers. While some of these are more generally applicable than others, I’ve had all of them come up in conversations about unrelated topics. When you’re applying for your next job, every other applicant is also going to list being good at web programming. It’s the other interesting details that make your resume really stand out.

Earlier this month, Mark Suster published what I consider to be one of the best startup blog posts of the year in his Earn or Learn article. The first point in the article refreshed something that young, mid-stage startup employees (like myself) frequently forget: your engineer’s share of the options isn’t going to make you rich. It may be a nice bonus, but there’s almost no chance of retiring in the unlikely event of a liquidation.

The second point resonated even stronger. If the job you’re in isn’t going to make you rich, it needs to be preparing you for the position that will. If you’re in a learning stage, keep that in mind every day on your way to work. Since the article was talking about advice for whether or not to take a new job it also left out one possibility: move. If you’re holding a job with little possibility of earning or learning, it may be time for a change.

My next few posts will give some areas of concentration for startup employees trying to learn as much as possible from their experience.

When I got Snow Leopard, I decided to do some house cleaning. I wiped the disk and reinstalled everything from scratch. I didn’t have any problems along the way until I went to install my favorite network protocol analyzer: Wireshark.

Installing is a simple matter of dragging the application into your Applications folder, but there’s also a startup item that sets some necessary permissions. To set that up, go into the Utilities folder on the Wireshark disk image, and drag the ChmodBPF folder onto the StartupItems shortcut. It’ll prompt you to authenticate and then copy. If you restart at this point, you’ll get an error message that says “Insecure Startup Item disabled. – “/Library/StartupItems/ChmodBPF” has not been started because it does not have the proper security settings.”

Using information from an Apple support article, I realized you need to change the owner of the scripts for them to be run on startup. Run the command below and everything will work fine!

cd /Library/StartupItems
sudo chown -R root:wheel ChmodBPF

Update (7/14/2010) – Make sure you restart your computer after running this command. The script only runs at startup, so just changing the permissions doesn’t do anything by itself. You have to restart for the script to run.

The final piece of Git I’ll be covering is using shared remote branches. This can be helpful if you have a team working on a development and a release branch, among other scenarios.

I’ll start by setting up a central repository and two working repositories based off it. I’ll be supplying an extra argument to the clone command to make things less confusing, this gives the name of the directory in which to check out the branch. For example, “git checkout first.git” (no argument) checks out into a directory called “first”. Using “git checkout first.git second” will check out into a directory called “second”.

Kleinschs-Macbook:tmp nick$ mkdir first.git && cd first.git
Kleinschs-Macbook:first.git nick$ git --bare init --shared
Initialized empty shared Git repository in /Users/nick/tmp/first.git/
Kleinschs-Macbook:first.git nick$ cd ..
Kleinschs-Macbook:tmp nick$ git clone first.git second
Initialized empty Git repository in /Users/nick/tmp/second/.git/
warning: You appear to have cloned an empty repository.
Kleinschs-Macbook:tmp nick$ cd second
Kleinschs-Macbook:second nick$ echo 'First file contents' > file1
Kleinschs-Macbook:second nick$ git add file1
Kleinschs-Macbook:second nick$ git commit -am'added first file'
[master (root-commit) 19b39e3] added first file
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file1
Kleinschs-Macbook:second nick$ git push origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 243 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
To /Users/nick/tmp/first.git
 * [new branch]      master -> master
Kleinschs-Macbook:second nick$ cd ..
Kleinschs-Macbook:tmp nick$ git clone first.git third
Initialized empty Git repository in /Users/nick/tmp/third/.git/

Now that I have two working repositories, I’ll go create a release branch on the second repository.

Kleinschs-Macbook:tmp nick$ cd second
Kleinschs-Macbook:second nick$ git checkout -b release
Switched to a new branch 'release'
Kleinschs-Macbook:second nick$ echo 'Second file contents' > file2
Kleinschs-Macbook:second nick$ git add file2
Kleinschs-Macbook:second nick$ git commit -am'added file2'
[release 48a00ee] added file2
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file2

Since I have this release branch, I’d like to expose it to the rest of the team so that everyone is looking at the same version. Adding a branch is as simple as doing a push with the name of the new branch. In this example, I’m telling Git to push to a remote branch that doesn’t exist, so it creates it.

Kleinschs-Macbook:second nick$ git push origin release:release
Counting objects: 4, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 292 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
To /Users/nick/tmp/first.git
 * [new branch]      release -> release

Listing the branches will show that the branch was created on the remote repository as well.

Kleinschs-Macbook:second nick$ git branch -a
  master
* release
  remotes/origin/master
  remotes/origin/release

Now let’s go over to the third repository and make sure we can access the release branch. First we do a pull to make sure we have the latest data from the remote server.

Kleinschs-Macbook:second nick$ cd ../third/
Kleinschs-Macbook:third nick$ git pull
remote: Counting objects: 4, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From /Users/nick/tmp/first
 * [new branch]      release    -> origin/release
Already up-to-date.
Kleinschs-Macbook:third nick$ ls
file1

We’re still not seeing the second file that was checked in on the release branch. This is because we’re still on the master branch at this point. In order to access the remote release branch, we need to create a local tracking branch for our changes. A tracking branch is a local branch that’s set up with a remote branch so that pushes and pulls go to the corresponding remote branch. In order to set up a tracking branch, just supply the “–track” flag to the branch command.

Kleinschs-Macbook:third nick$ git branch --track release origin/release
Branch release set up to track remote branch release from origin.
Kleinschs-Macbook:third nick$ git checkout release
Switched to branch 'release'
Kleinschs-Macbook:third nick$ ls
file1	file2

As you can see, we received the second file that was checked in on the release branch, so we should be ready to go. There’s one more thing I’d like to clear up. What if you have an existing branch that you’d like to have track a remote branch? The easiest way to do this is to edit your Git config file. Outputting the config from the the third repository will make this a little more clear.

Kleinschs-Macbook:third nick$ cat .git/config
[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
	ignorecase = true
[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	url = /Users/nick/tmp/first.git
[branch "master"]
	remote = origin
	merge = refs/heads/master
[branch "release"]
	remote = origin
	merge = refs/heads/release

The section for branch “release” has the relevant information. If you wanted to set up the second repository so its release branch was tracking the remote release branch, you just need to add these three lines to second/.git/config.

This concludes my series on Git. There’s a lot more to it than these four articles describe, but this should be a good jumping off point.

Using Git on a single machine may have its uses, but most people using Git are using it for its remote operations. Git functions in a variety of ways, I’ll be focusing on a central repository in this article. For more complicated workflows, see the Git Book.

The first thing to do is to set up a central repository. You can make it a normal Git repository like any other, but a few things will be easier if you make it what’s called a bare repository. This means that there’s no working copy, it just stores revisions. Adding the flag “–bare” to the init command sets it up as bare. I also like to add the “–shared” flag if you’re going to be sharing it across multiple users, this helps fix permissions. Look it up if you’re very curious. It also helps to name the shared repository ending in “.git”. If it’s set up that way, when people clone it, Git will lose the extension and just take the name. We’ll see that below.

Kleinschs-Macbook:tmp nick$ mkdir first.git && cd first.git
Kleinschs-Macbook:first.git nick$ git --bare init --shared
Initialized empty shared Git repository in /Users/nick/tmp/first.git/

Now that the bare repository is set up, we need to get something into it. There are two ways to connect to a remote repository: cloning and adding to an existing repository. I’ll add it to an existing repository first. This can be handy if you want to import existing files into a new repository.

Kleinschs-Macbook:first.git nick$ cd ..
Kleinschs-Macbook:tmp nick$ mkdir second.git && cd second.git
Kleinschs-Macbook:second.git nick$ git init
Initialized empty Git repository in /Users/nick/tmp/second.git/.git/
Kleinschs-Macbook:second.git nick$ echo 'First file contents' > file1
Kleinschs-Macbook:second.git nick$ git add file1
Kleinschs-Macbook:second.git nick$ git commit -am'Added file1'
[master (root-commit) 1a603a8] Added file1
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file1

Up to this point everything is standard. In order to commit changes into the central repository, we need to add the server and push the changes. The “remote” command takes care of remote repository setup in Git. The “remote add” adds a remote location, with the first parameter being the name and second being the location. In this example I’m using a local repository, but you could also do it via SSH, which I’ll show later. After you’ve added the remote location, use the “push” command to commit your changes to the remote branch. The first parameter is the remote location (using the name you just specified in the “remote add” command), second parameter is the remote branch for the commit. This pushes your current branch to the specified remote branch. For example, if I give the command “git push origin master”, it pushes my current branch to the master branch of the remote repository named origin. If you don’t want to push your current branch, you can specify which local branch to push in the command like this: “git push origin local-branch:remote-branch”. This would commit my branch named local-branch to the branch named remote-branch on origin.

Kleinschs-Macbook:second.git nick$ git remote add origin ../first.git
Kleinschs-Macbook:second.git nick$ git push origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 239 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
To ../first.git
 * [new branch]      master -> master

Now that we’ve got an initial commit in, let’s try the second way of connecting to a remote repository. The command “clone” copies everything from an existing repository and sets it up as a new repository. Again, in this example I’m using a local directory as the argument, but it can take other arguments including SSH.

Kleinschs-Macbook:second.git nick$ cd ..
Kleinschs-Macbook:tmp nick$ git clone first.git
Initialized empty Git repository in /Users/nick/tmp/first/.git/
Kleinschs-Macbook:tmp nick$ cd first
Kleinschs-Macbook:first nick$ ls
file1

Notice that we cloned “first.git”, so our clone is just named “first”. Let’s try adding a file through the newly cloned branch.

Kleinschs-Macbook:first nick$ echo 'Second file contents' > file2
Kleinschs-Macbook:first nick$ git add file2
Kleinschs-Macbook:first nick$ git commit -am'added second file'
[master 478a452] added second file
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file2
Kleinschs-Macbook:first nick$ git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit (working directory clean)

If you compared the .git/config files between second.git and first (the cloned repository), you’ll notice that in the cloned repository, there’s an extra line about our master branch:

[branch "master"]
	remote = origin
	merge = refs/heads/master

This sets up our local branch to link to origin’s master branch. This means that when we do remote operations from our master branch, we don’t have to specify the remote location or branch. This means that in order to push our changes, we just have to do a “git push”.

Kleinschs-Macbook:first nick$ git push
Counting objects: 4, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 300 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
To /Users/nick/tmp/first.git
   1a603a8..478a452  master -> master

Now that we’re pushing changes out frequently, we need to be able to download those changes from the central repository. The “fetch” command gets all revisions from a remote repository.

Kleinschs-Macbook:first nick$ cd ../second.git
Kleinschs-Macbook:second.git nick$ git fetch origin
remote: Counting objects: 4, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From ../first
   1a603a8..478a452  master     -> origin/master

You’ll see it downloaded them and refers to them using the notation “remote-location/remote-branch-name”. The fetch command doesn’t move the changes into your existing working copy, you’ll need to take care of this yourself. In order to pull the changes into your current local branch, you do a normal merge.

Kleinschs-Macbook:second.git nick$ git merge origin/master
Updating 1a603a8..478a452
Fast forward
 file2 |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file2

Since the process of fetching and merging is a frequent one, there’s a command that combines them: “pull”. Doing a pull runs a fetch and merges the specified remote branch into your current local one.

Kleinschs-Macbook:second.git nick$ git pull origin master
From ../first
 * branch            master     -> FETCH_HEAD
Already up-to-date.

Pulling and pushing is fairly simple, but there’s one common error I’ve run into that I’ll illustrate here. I’m going to push a commit from my second repository, then try to push a commit from my cloned repository.

Kleinschs-Macbook:second.git nick$ echo 'Third file contents' > file3
Kleinschs-Macbook:second.git nick$ git add file3
Kleinschs-Macbook:second.git nick$ git commit -am'added third file'
[master c114c2b] added third file
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file3
Kleinschs-Macbook:second.git nick$ git push
Counting objects: 4, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 324 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
To ../first.git
   478a452..c114c2b  master -> master
 
Kleinschs-Macbook:second.git nick$ cd ../first
Kleinschs-Macbook:first nick$ echo 'Fourth file contents' > file4
Kleinschs-Macbook:first nick$ git add file4
Kleinschs-Macbook:first nick$ git commit -am'added fourth file'
[master 17411ef] added fourth file
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file4
Kleinschs-Macbook:first nick$ git push
To /Users/nick/tmp/first.git
 ! [rejected]        master -> master (non-fast forward)
error: failed to push some refs to '/Users/nick/tmp/first.git'
To prevent you from losing history, non-fast-forward updates were rejected.
Merge the remote changes before pushing again.
See 'non-fast forward' section of 'git push --help' for details.

When I tried to do the second push, it was rejected. This is because Git requires that push operations result in a fast forward merge. If push operations didn’t have to be fast forward there could be unresolvable conflicts on the central server, which would leave things in a bad state for other users. For this reason, you need to take care of conflicts locally before doing a push. The simple fix for this is to do a pull and make sure you’re up to date before trying to do a push. If your changes really have to go in, there are ways to override the fast forward requirement, see the Git book for advanced options.

Kleinschs-Macbook:first nick$ git pull
remote: Counting objects: 4, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From /Users/nick/tmp/first
   478a452..c114c2b  master     -> origin/master
Merge made by recursive.
 file3 |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file3
Kleinschs-Macbook:first nick$ git push
Counting objects: 7, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 533 bytes, done.
Total 5 (delta 2), reused 0 (delta 0)
Unpacking objects: 100% (5/5), done.
To /Users/nick/tmp/first.git
   c114c2b..5890924  master -> master

Now let’s go back over to the second repository to make sure our changes went through correctly.

Kleinschs-Macbook:first nick$ cd ../second.git
Kleinschs-Macbook:second.git nick$ git pull origin master
remote: Counting objects: 7, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 5 (delta 2), reused 0 (delta 0)
Unpacking objects: 100% (5/5), done.
From ../first
 * branch            master     -> FETCH_HEAD
Updating c114c2b..5890924
Fast forward
 file4 |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 file4
Kleinschs-Macbook:second.git nick$ ls
file1	file2	file3	file4

Everything looks good! I spoke above about setting up repositories over SSH. You’ll need to have a valid account on the machine to connect to a Git repository. It’s usually helpful to set up a public/private key so you don’t have to specify the password every time. There are other way to connect, but they’re a bit more involved. Google and the Git Book are your friend here (start by looking up Gitosis). Here’s an example of the connect string to use with SSH.

Kleinschs-Macbook:second.git nick$ git clone ssh://nick@kleinsch.com/var/git/kleinsch.com.git/
Initialized empty Git repository in /Users/nick/tmp/second.git/kleinsch.com/.git/
remote: Counting objects: 2181, done.
...

I’ve made one mistake with SSH connect strings a couple of times now: this is not the same as the connect string for SCP. There’s no colon between the server and the path, unless you’re specifying a port. If you put one, you’ll just get a confusing error message, shown below.

Kleinschs-Macbook:second.git nick$ git clone ssh://nick@kleinsch.com:/var/git/kleinsch.com.git/
Initialized empty Git repository in /Users/nick/tmp/second.git/kleinsch.com/.git/
ssh: Could not resolve hostname kleinsch.com:: nodename nor servname provided, or not known
fatal: The remote end hung up unexpectedly

That covers the basics of remote operations. I’ll be doing one more post about Git focusing on remote branches.

In the first tutorial, I showed how to set up a Git repository and commit basic changes. You could get a lot done using only those commands, but you’d be missing out on most of the benefits of Git. Most of that could be done in SVN or CVS fairly easily. In this tutorial, I’ll go through setting up branches and merging changes, one of Git’s main strengths. Git was built from the ground up for frequent branching. In other version control systems, you may use branches for releases or major events, but in Git your day to day workflow revolves around branches.

If you don’t want to go back through the first post, the following commands will get you in sync with what I set up in the first post.

mkdir first && cd first
echo 'firstEdit' > file1
git init
git add file1
git commit -m'First commit'
echo 'secondEdit' > file1
echo 'anotherFile' > file2
git add file2
git commit -am'Made a second commit!'

Branches have been a useful tool in version control for quite some time. They allow multiple versions of the same project to be actively developed. One of the most common use cases for branches is bug fixing. Let’s say you have a project that’s been released and you’re working on new features. Maybe you’ve committed a bunch of files but they’re not ready to go out to production. A user finds a showstopping bug that needs to be fixed immediately. Some people would pull the code from the production release, hack together a patch, and push it out. With branches, you can get the production branch, fix the bug, check in the changes, then switch back to your development branch and merge the changes. This tracks your changes so if you have to fix another production bug, nobody has to remember what went out in the last patch.

The command ‘branch’ with no arguments will tell you which branches exist and put an asterisk next to the branch on which you’re currently working. If you pass in a name, Git will create a branch with that name.

Kleinschs-Macbook:first nick$ git branch
* master
Kleinschs-Macbook:first nick$ git branch development
Kleinschs-Macbook:first nick$ git branch
  development
* master

The ‘checkout’ command switches to another branch. One shortcut you can take is the ‘-b’ flag to ‘checkout’ which creates the branch and checks it out.

Kleinschs-Macbook:first nick$ git checkout development
Switched to branch 'development'
Kleinschs-Macbook:first nick$ git branch
* development
  master
Kleinschs-Macbook:first nick$ git checkout -b my-dev-branch
Switched to a new branch 'my-dev-branch'
Kleinschs-Macbook:first nick$ git branch
  development
  master
* my-dev-branch

The command ‘gitk’ brings up a window that shows the state of your branches graphically. By default, it hides branches not related to the current branch. The flag ‘–all’ is useful to show all branches. This is useful in figuring out complicated branching and merging scenarios. The most useful part of the display is the top left corner, which shows your branches in order of commits. More recent commits are at the top. Doing this on my project brings up this.

All of our changes are in the same place, so the branches show up on the same commit. Let’s make some changes.

echo -e 'secondEdit\n\nadded a line' > file1

At this point if you change branches, your uncommitted changes will follow. Each modified file will show up with an ‘M’ next to it when you issue the checkout command.

Kleinschs-Macbook:first nick$ git checkout development
M	file1
Switched to branch 'development'
Kleinschs-Macbook:first nick$ cat file1
secondEdit
 
added a line

This seems a little strange, but can actually come in handy. Let’s say you’re working on something and it turns into a bigger project than you thought. You may want to work on that on a branch instead. In that case you can checkout onto a new branch, commit your changes, and keep working.

Kleinschs-Macbook:first nick$ git checkout -b testing-theory
M	file1
Switched to a new branch 'testing-theory'
Kleinschs-Macbook:first nick$ git commit -am'first commit while testing something'
[testing-theory 42a287a] first commit while testing something
 1 files changed, 2 insertions(+), 0 deletions(-)
Kleinschs-Macbook:first nick$ gitk

This allows you to take advantage of version control for the things you’re working on that aren’t ready to be shared with other team members. You can work on this test branch as long as you want. Let’s say at the same time, you have to fix a bug on the production release, which for this project will be the master branch. First, checkout the master branch.

Kleinschs-Macbook:first nick$ git checkout master
Switched to branch 'master'

Let’s first create a branch for fixing this bug. It’s quick and easy, and we can track our changes. Then we can make whatever changes are necessary.

Kleinschs-Macbook:first nick$ git checkout -b fixing-bug
Switched to a new branch 'fixing-bug'
Kleinschs-Macbook:first nick$ echo 'secondEdit - add to first line' > file1
Kleinschs-Macbook:first nick$ git commit -am'fixed a bug in file1'
[fixing-bug 645e620] fixed a bug in file1
 1 files changed, 1 insertions(+), 1 deletions(-)
Kleinschs-Macbook:first nick$ gitk --all

Now that we’ve fixed the bug, we’ll roll it out to production. Let’s merge the bug fix into the master branch. For this, we use the command ‘merge’. You must checkout the branch you’re merging to, then supply the branch you’re merging from as the argument to the merge command.

Kleinschs-Macbook:first nick$ git checkout master
Switched to branch 'master'
Kleinschs-Macbook:first nick$ git merge fixing-bug
Updating 941bde0..645e620
Fast forward
 file1 |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)
Kleinschs-Macbook:first nick$ gitk --all

As you can see, we merged the changes into our master branch. This was actually a special type of merge: the fast forward merge. If the other branch already has all the commits from the current branch, Git will just add the commits from the other branch and point both branches at the same place. It’s like git is treating the commits from the fixing-bug branch as commits on the master branch.

Now let’s merge the changes from our testing-theory branch. This will conflict with the bug fix we just checked in, since both commits add to the first line. Usually Git is good at automatically merging, so changing two separate pieces of code in the same file won’t result in a conflict. In this example, we’ll have to resolve it. If conflicts are found, Git will leave markers in the conflicting files. After you fix the conflicts, you can run a commit to complete the merge.

Kleinschs-Macbook:first nick$ git merge testing-theory
Auto-merging file1
CONFLICT (content): Merge conflict in file1
Automatic merge failed; fix conflicts and then commit the result. 
Kleinschs-Macbook:first nick$ cat file1
<<<<<<< HEAD:file1
secondEdit - add to first line
=======
secondEdit
 
added a line
>>>>>>> testing-theory:file1

The first section shows the changes from master, the second shows the changes from testing-theory. Let’s keep both changes. I’m going to keep the first line from master and the last line from testing-theory.

Kleinschs-Macbook:first nick$ vi file1 
Kleinschs-Macbook:first nick$ cat file1 
secondEdit - add to first line
 
added a line
Kleinschs-Macbook:first nick$ git status
file1: needs merge
# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	unmerged:   file1
#
no changes added to commit (use "git add" and/or "git commit -a")

Now we’re ready to finish the merge. You commit this the same as a regular commit. Since testing-theory doesn’t have the bug fix that we used to patch master, this will not be a fast forward merge.

Kleinschs-Macbook:first nick$ git commit -am'Merged changes from testing-theory branch'
[master d6132fa] Merged changes from testing-theory branch
Kleinschs-Macbook:first nick$ gitk --all

The picture here gets a little complicated, but it shows that our master branch now incorporates changes from both the fixing-bug and testing-theory branches.

The complicated stuff is over! Just two more bits to clear up. Let’s create a branch and make some changes.

Kleinschs-Macbook:first nick$ git checkout -b another-branch
Switched to a new branch 'another-branch'
Kleinschs-Macbook:first nick$ echo 'bad-change' > file2

If you don’t like the change and want to get rid of it, you can use the checkout command to get rid of it. SVN users: the ‘revert’ command in Git is not the same as the revert command in SVN! If you’re thinking of reverting changes made to a file, make sure to use the checkout command.

Kleinschs-Macbook:first nick$ git checkout file2
Kleinschs-Macbook:first nick$ cat file2
anotherFile
Kleinschs-Macbook:first nick$ git status
# On branch another-branch
nothing to commit (working directory clean)

Let’s say it turns out you didn’t need this branch, let’s get rid of it. You first need to switch away from this branch. Then use the ‘-d’ option to the branch command to delete unnecessary branches.

Kleinschs-Macbook:first nick$ git checkout master
Switched to branch 'master'
Kleinschs-Macbook:first nick$ git branch -d another-branch
Deleted branch another-branch (was d6132fa).
Kleinschs-Macbook:first nick$ git branch
  development
  fixing-bug
* master
  my-dev-branch
  testing-theory

You can even delete the branches you’ve committed. This won’t mess up your branching history, it just removes the branch label from those commits.

Kleinschs-Macbook:first nick$ git branch -d fixing-bug
Deleted branch fixing-bug (was 645e620).
Kleinschs-Macbook:first nick$ git branch -d testing-theory
Deleted branch testing-theory (was 42a287a).
Kleinschs-Macbook:first nick$ git branch -d my-dev-branch
Deleted branch my-dev-branch (was 5bd6207).
Kleinschs-Macbook:first nick$ gitk --all

This still shows the same history, we’ve just removed the named branches not in use. Finally, if you’re doing development, you may need to incorporate the changes that have gone into the master branch so you can start at the same point as your release.

Kleinschs-Macbook:first nick$ git checkout development
Switched to branch 'development'
Kleinschs-Macbook:first nick$ git merge master
Updating 941bde0..d6132fa
Fast forward
 file1 |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)
Kleinschs-Macbook:first nick$ gitk --all

That’s about it for branching and merging. At this point the only thing the only major thing left is setting up remote operations. I’ll cover that in the next part of this tutorial.

I just started using Git for source control. Having used CVS and SVN extensively, I thought I had a decent background on version control and would be able to pick it up quickly. I quickly was overwhelmed by the amount of concepts and explanations needed in the documentation. Hint to the folks writing the Git book: start with simple concepts and build up from there. I don’t need to know how Git stores its files in the first chapter. I don’t need to know what a fast forward merge is. Give me one chapter that has a simple workflow example, then jump into the explanations of the internals and advanced features. I had to read through 50 pages of the book to figure out a basic remote workflow. Here are some of the bits I’ve gleaned. I’m still a Git beginner, so tips are always appreciated.

I’ll assume you have Git set up already, there are tutorials on the web for the wide variety of supported platforms. Once you’re set up with Git, you should be able to run ‘git –version’ at the command line and see a version string (like “git version 1.6.3.2″). All git commands are run in the format ‘git COMMAND_NAME OPTIONS’. Running ‘git –help’ will list all commands. Running ‘git help COMMAND_NAME’ will give a man page about that command. For example, to get information about the add command, you can run ‘git help add’.

Setting up a Git repository is simple. You can use an existing directory or create something from scratch. I’ll start out fresh. The ‘init’ command sets up a new repository.

Kleinschs-Macbook:tmp nick$ mkdir first && cd first
Kleinschs-Macbook:first nick$ echo 'firstEdit' > file1
Kleinschs-Macbook:first nick$ git init

Now we’re set up with a Git repository in this directory. The ’status’ command gives you information about your working set.

Kleinschs-Macbook:first nick$ git status
# On branch master
#
# Initial commit
#
# Untracked files:
#   (use "git add ..." to include in what will be committed)
#
#	file1
nothing added to commit but untracked files present (use "git add" to track)

To make a commit in Git, you first do an ‘add’ of all files you want to be included in the commit, then a ‘commit’. The commit command will prompt for a message using your favorite editor, or you can use the ‘-m’ flag to add the message at the command line.

Kleinschs-Macbook:first nick$ git add file1
Kleinschs-Macbook:first nick$ git status
# On branch master
#
# Initial commit
#
# Changes to be committed:
#   (use "git rm --cached ..." to unstage)
#
#	new file:   file1
#
Kleinschs-Macbook:first nick$ git commit -m'First commit'
[master (root-commit) 4cc0433] first file
1 files changed, 1 insertions(+), 0 deletions(-)
create mode 100644 file1
Kleinschs-Macbook:first nick$ git status
# On branch master
nothing to commit (working directory clean)

Let’s say we want to make a change. We’ll modify the first file and add another.

Kleinschs-Macbook:first nick$ echo 'secondEdit' > file1
Kleinschs-Macbook:first nick$ echo 'anotherFile' > file2
Kleinschs-Macbook:first nick$ git status
# On branch master
# Changed but not updated:
#   (use "git add ..." to update what will be committed)
#   (use "git checkout -- ..." to discard changes in working directory)
#
#	modified:   file1
#
# Untracked files:
#   (use "git add ..." to include in what will be committed)
#
#	file2
no changes added to commit (use "git add" and/or "git commit -a")

Git detects that we’ve changed one file and added another. If you want to see the changes you made, you can use the ‘diff’ command to show a diff of the files.

Kleinschs-Macbook:first nick$ git diff file1
diff --git a/file1 b/file1
index dc2bdc4..1837f2f 100644
--- a/file1
+++ b/file1
@@ -1 +1 @@
-firstEdit
+secondEdit

We could add the change and commit, but there’s a slightly easier way. As the status output describes, you can use the ‘-a’ flag for commit to automatically commit all modified files. It will not add new files, you’ll still have to do add those yourself. Let’s add the second file and commit the whole thing.

Kleinschs-Macbook:first nick$ git add file2
Kleinschs-Macbook:first nick$ git commit -am'Made a second commit!'
[master 74ec253] Made a second commit!
2 files changed, 2 insertions(+), 1 deletions(-)
create mode 100644 file2
Kleinschs-Macbook:first nick$ git status
# On branch master
nothing to commit (working directory clean)

The last thing to cover for right now is looking at past history. You use the ‘log’ command to view commit history.

Kleinschs-Macbook:first nick$ git log file1
commit 8ebf88b3d99309c1bd245156459a24549cf11ee8
Author: Nick Kleinschmidt <nick.kleinschmidt@gmail.com>
Date:   Sat Aug 15 09:28:26 2009 -0400
 
    Made a second commit!
 
commit 7801dc66b2b3b5029e888ad35e5f0405584b4ff1
Author: Nick Kleinschmidt <nick.kleinschmidt@gmail.com>
Date:   Sat Aug 15 09:24:47 2009 -0400
 
    first commit
Kleinschs-Macbook:first nick$ git log file2
commit 8ebf88b3d99309c1bd245156459a24549cf11ee8
Author: Nick Kleinschmidt <nick.kleinschmidt@gmail.com>
Date:   Sat Aug 15 09:28:26 2009 -0400
 
    Made a second commit!

With this setup, you can work locally, changing and committing to your hearts content. At this point, it’s fairly similar to most traditional version control systems. There’s still a lot to cover! Next time, I’ll get into setting up a remote repository, then we’ll dive into branching and merging.

I’ll assume you’re starting with a stock Debian 5.0 system and have set up sudo access for your account. I’ll be using the user nick as my personal user for this setup.

First we need install the prerequisites: Apache, PHP, and MySQL. It’ll ask you for a root password for MySQL, make sure you hold onto that. We’ll need it later.

sudo apt-get install apache2 mysql-server php5 php5-mysql

Now we need to make sure that Apache is configured with the modules needed for Wordpress.

sudo a2enmod rewrite
sudo a2enmod php5

WordPress uses a MySQL database to store your blog posts and comments, so we need to create a MySQL database for wordpress. MySQL will ask you for the root password you created before. Make sure to save the password you set up for the wordpress user, as this is what WordPress will use to connect to the database.

mysql -u root -p
CREATE DATABASE `wordpress`;
grant all privileges on `wordpress`.* to 'wordpress'@localhost identified by 'ANOTHER-PASSWORD'; 
flush privileges;

Need to set up WordPress with a directory so we can use it. Download WordPress from their site and stick it in your home directory.

cd /var/www
sudo mkdir sites && cd sites
sudo cp ~nick/wordpress-2.8.2.tar.gz .
sudo tar xzvf wordpress-2.8.2.tar.gz
sudo touch wordpress/.htaccess
sudo chown -R nick:www-data wordpress
sudo chmod -R g+w wordpress

We changed the group and gave write permissions so WordPress will be able to set up its own config files. We set up the .htaccess file in advance because it’s easier to let WordPress change it based on the URL settings.

In order to serve the website, we need to set up an Apache Virtual Host. Create a file in /etc/apache/sites-available (mine is kleinsch.com) for your site and add the following code.

<VirtualHost *:80>
        ServerName kleinsch.com
        ServerAlias www.kleinsch.com
        ServerAdmin youremail@yourhost.com
        DocumentRoot /var/www/sites/wordpress
        <Directory /var/www/sites/wordpress>
                Options FollowSymLinks
                AllowOverride All
        </Directory>
</VirtualHost>

Enable the site within Apache and restart:

sudo a2ensite kleinsch.com
sudo /etc/init.d/apache restart

You should see no warnings. Open up your browser and navigate to ‘http://yoursite.com/wp-admin/install.php’.

The first page will tell you WordPress needs to create a config file, we want it to do that. On the next page, enter the database information you set up above. Leave the defaults for the encoding and table prefix. Enter a title for your blog, and you’re up and running!