FlightGear Git for laymen

Git for Laymen

Git, and its fellow Version Control Systems are a domain of geeks - who are patently incapable of explaining anything in simple terms most of the time. Because of this, many a layman has fled in terror from what is, when all's said and done, easy to use.

What is Git?

Git is a Version Control System, meaning that it tracks changes to files - in other words, if you make a change to a file known to Git, or commit the change as the expert would put it, Git stores what parts of the file have changed between the last version and the current version. That makes it possible to do a lot of great things, the most mind-soothing among them being the ability to get the old version back in case it turns out you've broken something.

What does Git do for me?

Another thing Git does is distribute change. That means, additionally to committing things to the Git repository, you can also get the changes others made from the Git repository - thus keeping your local copy of whatever is kept in the repository current. That is the use most laymen will be most interested in. In practical terms, that means you can at any time get all the changes the developers made just by updating your copy from the repository - instead of having to re-download the whole data (or trying to scrape together the changed files manually, a path that leads to insanity without any stop signs or speed limits). With a large repository like Flightgear Base Data for example, the difference is a few kilobytes instead of 15 gigabytes.

What do I need to use a Git repository that way?

Basicly, all you have to do is install a git client on your machine. For windows users, TrotoiseGit, which is free for download, would be the option of choice, for Linux/Unix users it's just plain git, available from your favorite software repository. Both are rather trivial to set up - the only confusing thing is that they may require you to supply a name and an email adress on install - don't get panicky, it's just a prerequisite Git has for use cases you'll never see unless you decide to come to the geek side of life. Needs to be done, just like you have to klick "I accept" to install most (proprietary) software.

How do I use the git repository to update Flightgear stuff?

Git has a score of very confusing options that allow you to do stuff that boggles the mind of even an established geek. To achieve what you, the layman, will want to do, a total of two commands are totally sufficient.

Initial cloning

The first step to using the Git data for your own purposes is to grab a copy from the repository. Here's how to do that.

This description uses the linux commandline version of the git commands, but in principle you do the same with TrotoiseGit, only the commands are in the context menu there.

First, navigate to where you want the checkout to live

$ cd /home/user/data/git-repos

Then, you clone the repository. To do that, you have to know the URL of the repository you want to be cloning. Those are found on the Flightgear Gitorious page.For this example, we'll be using the Flightgear Base Data repository fgdata, but the principle is exactly the same for simgear or flightgear source. All that changes is the URL to clone.

$ git clone git://gitorious.org/fg/fgdata.git

Note also how you don't have to create a directory for the checkout. A well-setup git repository does that for you with the clone command.

After you hit enter on that line, it's time to lean back and get a cup of coffee, because that specific repo is really quite huge - almost 15 GB of data as of writing this. (There is a better method for cloning huge repos like this, it's described on this page: FlightGear and Git,but it's likely that's exactly the page you fled here from.)

Now, once that operation completes (without errors hopefully), you're done! Try

$ cd fgdata
$ ls

and enjoy.

Keeping it current

Up to this point, we haven't done anything we couldn't have achieved with an archive file. That is, we have, but not in a way you, a layman, are in any position to recognize. Now is the time to take advantage of this fact.

Let's say you've buggered the guys in the IRC channel until finally somebody has fixed the bug in your favorite airplane just to get rid of you. Now how do you personally get that change? If you had been downloading an archive, you'd have to wait for the archive to be rebuilt, download the whole thing again, and iron it on over the old data. Not so with Git - here's what to do. Navigate to the place where your repository lives, in our example like this:

$ cd /home/user/git-repos/fgdata

Note that this time, we're cding into the directory. Now get all the changes since you cloned the repository like this:

$ git pull

That's all. Watch the numbers dance - it'll be much quicker this time than the last time, because only the changes in the files need to be transmitted - and once the command returns, you can jump into your now (hopefully) bug-free airplane and take her for a spin

A word about troubleshooting

This wouldn't be a good article without a word about troubleshooting. The process described above is really rather reliable and will work 99% of the time, but sometimes it does break down - mostly because you inadvertedly changed a file that somebody else changed in the "official" repository. If Git finds a conflict, e.g. a file having been edited by you AND somebody else since the last pull - it will refuse to just clobber the local changes.

Now - if you DID change the file actively, it's time you went over to a real git tutorial and found out about merging changes. If you didn't, you can revert the changes to the baseline of the repository, that is, reset the file(s) to how it was when you last pulled the changes:

$ cd /home/user/git-repos/fgdata
$ git reset
$ git pull

If it works, all is fine. If Git still complains, e.g. about not being able to "fast-forward" the changes, you'll have to tell it to try a little harder (and with less respect to what it might clobber) to reset your working copy:

$ git reset --hard

Sometimes, IT is simple. This command should undo everything you did in your working copy, that is, get the entire working copy back to the state it was when you last pulled. In 99% of the trouble, this is the end of it, and a

$ git pull

will work. If it still doesn't, your local clone has gotten a nasty dent somewhere. In this case, you can either seriously dive into git and fix it, or delete the whole repository folder and clone anew:

$ cd /home/user/git-repos/
$ rm -rf fgdata
$ git clone git://gitorious.org/fg/fgdata.git

Where do I take it from here?

To be honest: for most laymen this is the end of the trail, and you'll live happily ever after.

If however your interest has been piqued and you want to know more about Git in particular and VCS in general - and how they can help you tweak and twitch your copy of flightgear - more power to you.

First, I'd recommend browsing the net for a good git tutorial - a very good one is available from Linus Torvalds, the famous inventor of Linux - and father of Git - but you'll have to find out which one works for you. Also read FlightGear and Git, the official wiki page on doing Git the Flightgear way.