FlightGear and Git
|FlightGear Git on:|
Git is a version control system used by the FlightGear project to store all of the files required to build FlightGear, as well as data (mainly aircraft). Git tracks updates to every file as developers around the world work together concurrently to create new versions.
While new FlightGear features and additions are in development, they are available from Git before they are available in the standard release version. Using Git allows a user to build the newest possible version of FlightGear from the latest source files, to experiment with new aircraft or other features. However, it's not a beginner's tool. Using Git can expose the user to unstable features that show ugly error messages, or crash the computer.
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. For most users and developers the most interesting ones of each are:
- next The current tip of new development. This branch should always compile and run, but various things could be broken.
- release/* The branch subdirectory containing former and, if there is one, upcoming releases.
For other available branches have a look at our repository at gitorious.org. The following two branches are as of now (May 2011) very much out of date. Do not use.
- 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.
FlightGear data's branches of interest are:
- master The one that is used with the next branch of the source.
- release/* Same as for the source.
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
- Check on gitorious for valid projects: http://gitorious.org/fg
- Cloning Simgear
- Cloning FlightGear
- Cloning FGData
By default you will be checking out the next branch of SimGear and FlightGear and the master branch of FGData. 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.
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.
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
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.
- 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.
- will show all tags of the history of the active branch.
- will update the local repo from the remote one.
Except for the initial clone command this is identical 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.
At the time of writing the data repository is about 3.4 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.
To make individual changes, like editing a joystick file or add a plane to fgdata or patch the source code, it is recommended to create a local branch inside that repository. The following commands will describe a way to achieve this. But have in mind, that this is very basic and only suits for users who have minor changes.
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 now apply your individual stuff there and start FlightGear to verify the changes are proper.
If you conclude they are, you have to tell git about those changes:
- will give you a list of files that have been altered or that are new.
git add -i
- will show the files that have been altered and give you options on what to do next.
git adddoes not actually add the changes to master.local but adds them to the index.
- [a]dd will add new paths/files (called untracked in status) from the working tree to the index. This has to be done only if you have added paths/files, like an aircraft, to the working tree.
- If git finds more than one untracked file/path, it will give you a numbered list and prompt to select which ones should be added. An empty input will exit this mode. See "Interactive mode" in man git add for more details.
- [u]pdate is the next step and will update the altered and tracked files to the index in the same manner as explained in add untracked paths above.
- will commit the indexed updates to the master.local branch. It opens a list of the updates in your standard editor. You may add a comment to that file describing the object of the commit. Save and exit the editor. You have now committed your changes inside the working tree to your personal branch.
To update that personal branch from the remote one do the following steps:
git fetch # update repo git checkout master # switch to master branch git rebase origin/master # update master branch git checkout master.local # switch back to the individual branch git rebase master # update it
Some more helpful commands
git help [commad]
- 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!
Tracking a release branch
git branch -t -l release/2.6.0 origin/release/2.6.0 git checkout -b release/2.6.0
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
The bundle may be periodically updated and bundles from different sources need not be the same. The file size for the above bundle dated 2011-12-13 is almost 4GB :-), while the md5 checksum is
$ md5sum fgdata.bundle 145f4e190fd1a02fd75c1d508b8c2ec3 fgdata.bundle
Caution: should be that. If the bundle is updated, not be the same.
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" [...] $ cd fgdata $ git checkout -b master-tmp Switched to a new branch 'master-tmp' $ git remote rm origin $ git remote add origin git://gitorious.org/fg/fgdata $ git fetch origin remote: Counting objects: 5011, done. remote: Compressing objects: 100% (2206/2206), done. remote: Total 3512 (delta 1948), reused 2321 (delta 1239) Receiving objects: 100% (3512/3512), 161.20 MiB | 474 KiB/s, done. Resolving deltas: 100% (1948/1948), completed with 698 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 branch] releases/2.2.0 -> origin/releases/2.2.0 * [new tag] last-cvs -> last-cvs * [new tag] mapserver -> mapserver From git://gitorious.org/fg/fgdata * [new tag] last-cvs -> last-cvs * [new tag] mapserver -> mapserver $ git branch --track master origin/master Branch master set up to track remote branch refs/remotes/origin/master. $ git checkout master Checking out files: 100% (1117/1117), done. Switched to branch 'master' $ git branch -D master-tmp Deleted branch master-tmp.
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
You should be suspicious if based on the printed progress you estimate the data download during the fetch will exceed 1GB (assuming the bundle is not terribly outdated).
For future updates just do a
Make a clone of fgdata, by clicking the clone repository button on Gitorious. Commit your stuff first to your local repository (git commit), then perform the following commands:
git fetchto get the latest commits from fgdata/
git rebase origin/masterplace your own commit on top of the latest commits/
git push firstname.lastname@example.org:~name/fg/namess-fgdata.gitpush your commits to your fgdata clone. Replace the url with your fgdata-clone's SSH url!
Go to your fgdata-clone on Gitorious and click the "Request merge" button on the right. Write a short summary in which you explain what your commit(s) do. Then choose the following settings:
- Target directory: fgdata
- Target branch: master
- Source branch: master
Next select the commits you'd like to include in your merge request and click "Create merge request".
This step is for developers with fgdata commit access only!
To push merge request to fgdata, the following workflow can be followed:
git checkout -b integration # the integration branch should not yet exist. You can use any name you'd like git pull git://gitorious.org/fg/fgdata.git refs/merge-requests/1 # make sure you change 1 to the id of the merge request git rebase master # place the new commits on top of existing commits (without ugly "Merge branch into ...") git checkout master git cherry-pick b049e1d # repeat this for each commit you'd like to push git push
Git tutorials and resources
- Git documentation and tutorials
- Git as a way of life.
- The Git Cheat Sheet and the Git Cheat Sheet Extended Edition
- Egg, a cool Git emacs mode.
- A guide to using Git on Windows
- Git on Windows Go! (Setting up msysgit on Windows)
- Git on Windows (webcast)
- qgit - interactive git repository viewer and frontend
- Additional Resources WRT running git on Win32