FlightGear Git

From FlightGear wiki
Revision as of 11:24, 10 November 2010 by Flughund (Talk | contribs) (very very minor changes ;))

Jump to: navigation, search

In May 2010, after a hardware failure on the CVS servers, the FlightGear project changed version control system from CVS to Git. The Git repositories are located at Gitorious and at the Mapserver.

Due to the recent switch, we are currently doing our best on providing manuals for obtaining FlightGear through Git. The following articles are work in progress:


Much has been written on the advantages of Git over CVS. For us, some advantages are:

  • Much better support for branches and merging branches. This is especially important for creating bug-fix releases for major releases while still allowing work on the next major release to continue. It is also very nice for a developer's personal workflow.
  • Easier path for contributors to submit changes and developers to integrate them;
  • Much better support for everyday tasks like searching the project history for changes, viewing changes, bisecting the project history to find the original source of a bug.

Also, as noted before, the CVS servers had a hardware failure on May 2010, speeding up FlightGear's change to Git.

Repositories and Branches

For historical reasons there continue to be separate repositories for SimGear and FlightGear source. There are 3 interesting branches in the repositories. Listed in order from least stable to most:

  • next The current tip of new development. This branch should always compile and run, but various things could be broken.
  • master The tip of stable, tested new features. If we were to make a new release today, we would start from the tip of this branch. New features that have been "cooking" in the next branch for a few days or weeks will be merged here.
  • maint Bug fixes for the most recently released Flightgear. When a release is made from master, this branch is reset to it.

This arrangement follows the scheme used by the Git maintainers. This description is very technical; you will surely have achieved git-fu if completely understand it. However, the idea of maintaining several branches of different stability is common in collaborative software projects.

Clone and handle Repositories

Quick checkout

  1. Check on gitorious for valid projects: http://gitorious.org/fg
  2. Cloning Simgear
  3. Cloning FlightGear
  4. Cloning FGData

By default you will be checking out the next branch of SimGear and FlightGear. This is probably what you want if you want to assist with reporting bugs and the like before they are release as a proper release version.

For dummies

Some basic git commands on how to clone, update and handle local git repositories. Except the initial git clone for each repository all commands have to be executed from within the target folder.

Cloning SimGear

git clone git://gitorious.org/fg/simgear.git [target]
the folder target will be created and a clone of the SimGear repo stored inside it. If no target is given the new folder's name is simgear.

cd into the new folder. You are then inside the working tree of this git repo. The repo itself is stored inside the subfolder .git, which we mustn't edit manually. Git will take care of that.

git branch
will show the active branch. Right after download this will be * next, that means the content of the working tree is the bleeding edge of SimGear's source code.
git branch -a
will list all branches of a git repository. The one marked with an asterisk (*) is the active one.
git checkout master
will change the active branch to master. Means, that the content of the working tree will be changed to that state.
git checkout v2.0.0
will activate the state of the code inside the master branch at the time FG 2.0.0 was released.
git tag
will show all tags of the history of the active branch.
git pull
will update the local repo from the remote one.

Cloning FlightGear

Except for the initial clone command this is identic to Cloning SimGear.

git clone git://gitorious.org/fg/flightgear.git [target]

To successfully compile fgfs Flight- and SimGear's working tree must have the same state.

Cloning fgdata

At the time of writing the data repository is about 2.6 GB. Continuing an interrupted cloning of a repository is not supported with git. Therefore, if you have a slow or unstable connection to the internet, it is recommended to download the fgdata.bundle.

Also have in mind, that the repository plus the working tree will be more than twice the size of the download on your local filesystem.

There is neither a next branch nor any tags in that repository. If you want to build FlightGear 2.0.0 you may fetch the data (FlightGear-data-2.0.0.tar.bz2) at one of the mirrors.

git clone git://mapserver.flightgear.org/fgdata/ [target]
if no target is given the new folder's name is fgdata

cd into the new directory and verify it's state with git branch. If it isn't * master, do a git checkout master.

Local Branch

To make individual changes, like adding/editing a joystick file to fgdata or patch the source code, it is recommended to create a local branch inside that repository:

cd into the repositories folder, e.g. fgdata:

git checkout -b master.local master
a new branch master.local is created out of the master branch and set as the active one. You may apply your individual stuff there.

To update that personal branch from the remote one do the following steps:

git checkout master           # switch to master branch
git pull                      # update it
git checkout master.local     # switch back to the individual branch
git rebase master             # update it

Some more helpful commands

git help
git help [commad]
git apply
apply a patch to files and/or to the index http://www.kernel.org/pub/software/scm/git/docs/git-apply.html
git checkout -f
may be used to throw away any local changes to the working tree. Use with care, as any option that name is -f or --force, and only after reading git checkout help!


For the FlightGear-data there are also bundles (snapshots) available that can be retrieved with your favourite download manager. This way you can resume interrupted downloads. After unpacking only a comparatively small amount of data has to be transferred from the git server to synchronize your repository.

Download the bundle from

$ wget http://flightgear.mxchange.org/pub/fgfs/fgdata.bundle


$ wget http://peter-server.homelinux.net/fgdata/fgdata/fgdata.bundle

The bundle may be periodically updated and bundles from different sources need not be the same. The file size for the above bundle dated 2010-06-09 is 2394168314, while the md5 checksum is

$ md5sum fgdata.bundle
2996221bd2b8ab7740f332f49396cf56  fgdata.bundle

Do the following steps to extract the bundle and bring the repository up to date:

$ git clone fgdata.bundle fgdata
Initialized empty Git repository in fgdata/.git/
warning: unrecognized header: -deg" - /orientation/roll += "-deg" - /position/altitude += "-ft" - /position/altitude-agl += "-ft" - /position/latitude += "-deg" --/position/longitude += "-deg" - /radios/adf/frequencies/selected += "-khz" - /radios/adf/frequencies/
warning: remote HEAD refers to nonexistent ref, unable to checkout.
$ cd fgdata
$ git branch master-tmp origin/master
Branch master-tmp set up to track remote branch refs/remotes/origin/master.
$ git remote rm origin
$ git remote add origin git://gitorious.org/fg/fgdata
$ git fetch origin
remote: Counting objects: 5596, done.
remote: Compressing objects: 100% (2919/2919), done.
remote: Total 4266 (delta 2540), reused 2166 (delta 1297)
Receiving objects: 100% (4266/4266), 117.93 MiB | 1374 KiB/s, done.
Resolving deltas: 100% (2540/2540), completed with 628 local objects.
From git://gitorious.org/fg/fgdata
 * [new branch]      PRE_OSG_PLIB_20061029 -> origin/PRE_OSG_PLIB_20061029
 * [new branch]      master     -> origin/master
 * [new tag]         last-cvs   -> last-cvs
 * [new tag]         mapserver  -> mapserver
$ git branch -D master-tmp
Deleted branch master-tmp.
$ git branch --track master origin/master
Branch master set up to track remote branch refs/remotes/origin/master.
$ git checkout

If you get an error at git fetch origin try:

$ git remote rm origin
$ git remote add origin git://mapserver.flightgear.org/fgdata/
$ git fetch origin

For future updates just do a git pull.

External links

Git tutorials and resources