FlightGear Git

Git is a version control system used by the FlightGear project to store all of the files required to build the FlightGear, including all the programs, the data (e.g. aircraft), supporting tools, etc. 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 users 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.

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 a mirror is hosted 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:

• Mac OS X: FlightGear Git on Mac OS X
• Windows: FlightGear Git on Windows
• in addition Howto:Start using git provides a quick introduction to using git.

Motivation

Much has been written on the advantages of Git over CVS. For the FlightGear project, 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.

Manipulating the GIT

Overview

For a detailed description see the description of the 4 repositories (A,B,C,D) in the following chapters

A) 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.

B) Create your own workspace on Gitorious

Prior to be able to manipulate GIT-data you must be a registered User and be logged in as such. See

https://gitorious.org/users/new

https://gitorious.org/login

Then check on http://gitorious.org/fg for the available projects. See e.g.:

• flightgear
• simgear
• fgdata
• getstart
• etc.

Create your own "GIT-Clone" (as a space to work in) by activating the "Clone repository" button of the wanted project. By default you will be cloning the next branch of that project --> that is the actual repository including the newest, not yet formally distributed, changes. That is probably what you want if you want to

• assist with reporting bugs before they are released as a proper release version
• or participate in the design
• or similar

If you are interested in other branches/versions see the button "Source Tree". But keep in mind: To successfully compile fgfs Flight- and SimGear's working tree must have the same state!

The created GIT-clone will be https://gitorious.org/~YourUID ("YourUID" being your ID you logged in with, and do not forgett the "~" in front of it!))

C) Create a "master" on your local PC

All the following is shown as performed in an UBUNTU "Terminal" environment! Please adapt especially the directory trees according to your Operating-System!

1. Create a unique folder on your PC, e.g. "..\GIT"
2. change into that folder and use the "git clone" commands to clone the wanted repository
   • if you need/want more informations about unique GIT-commands, input "git help [command]" (e.g. "git help clone")
3. use one of the following commands (or similar) from within that "..\GIT"-folder:

• for cloning SimGear use:

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

To successfully compile fgfs Flight- and Sim-Gear's working tree they both must have the same state.

• for cloning FlightGear use:

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

To successfully compile fgfs Flight- and Sim-Gear's working tree they both must have the same state.

• for cloning fgdata use:

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

By executing one of the above commands the folder target will be created and a clone will be stored inside it. If no target is given the new folder's name is the GIT-name (i.e.: "../GIT/simgear", "../GIT/flightgear", "../GIT/fgdata").

cd into the new folder [target]

You are now inside the working tree of this git repo. The repo itself is stored inside the subfolder ../GIT/[target]/.git, which we mustn't edit manually. Git will take care of that.

Notice the "." in front of the name: In Linux that indicates a hidden file, for which you might have to enable "show hidden files"!

git branch

will show the active branch. e.g.

..GIT/fgdata$ git branch
* master
 master.local  (<-- this branch will not be there initially!)

Right after download the active GIT-repository-branch will be "next", which on your PC is called "master". The "*" in front means that this is now the active one! i.e. the content of the active working tree is the bleeding edge of the source code.

git branch -a

will list all branches of a git repository. The one marked with an asterisk (*) is the active one. e.g.:

..GIT/fgdata$ git branch -a
* master
  master.local  (<-- this will not be there initially!)
  remotes/origin/HEAD -> origin/master
  remotes/origin/PRE_OSG_PLIB_20061029
  remotes/origin/Short_Empire-public
  remotes/origin/Work
  remotes/origin/master
  remotes/origin/release/2.4.0
  remotes/origin/release/2.6.0
  remotes/origin/releases/2.2.0

You now have your local "GIT-master". But: To make individual changes (like editing a joystick file) add a plane to fgdata or patch the source code. It is always recommended to create a local branch inside that "master" repository. In the chapter "D) Editing Data" we 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.

Special for fgdata:

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 e.g. you want to build FlightGear 2.0.0 you must fetch the data (FlightGear-data-2.0.0.tar.bz2) at one of the mirrors.

fgdata.bundle

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

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
$ 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
$ git branch --track master origin/master
$ git checkout master
$ git branch -D 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).

D) Edit and Commit Data

Edit

Switch into the branch in which you want to edit your changes (without affecting your master yet!). We will use for that branch the name "master.local". Thus:

git checkout master

..GIT/fgdata$ git checkout master
Switched to branch 'master'

will change the active branch to master. Means, that the content of the working tree will be changed to that state.

In case you get an error like

GIT/fgdata$ git checkout master
Already on 'master'
Your branch is ahead of 'origin/master' by 2 commits.

you need to resync your master with e.g.:

git fetch

git checkout -b master.local master

..GIT/fgdata$ git checkout -b master.local master
Switched to a new branch 'master.local'

Gnerates the new "master.local" and switches to it.

In case you get the response

fatal: A branch named 'master.local' already exists.

• you have to define another name for that branch
• or delete it:

  Try first: "git branch master.local -d" ⇒ that will delete it if it is "clean"

  If needed do: "git branch -D master.local" ⇒ that forces a delete - even if there is uncommitted work in it !!

You may now

• apply your planned changes into the affected "/GIT/subdir"
• start FlightGear to verify they are proper/functional
• then check what was done:

git status

(the output may take some time to appear!

see e.g. a dummy-example:)

..GIT/fgdata$ git status
# On branch master.local
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   Aircraft/ATC-ML/Version
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#	Aircraft/ATC-ML/Version (copy)
#	Aircraft/DUMMY/
no changes added to commit (use "git add" and/or "git commit -a")
...... etc.

This gives you a list of files that have been altered or that are new. In the above (dummy example) you see:

• the already existing file "Aircraft/ATC-ML/Version" was modified
• a new file "Aircraft/ATC-ML/Version (copy)" was added
• and a new directory "Aircraft/DUMMY/" was added, including all its files

If that is what you wanted/needed continue with the following (otherwise correct your work first)

So we want to "add" those changes:

git add "Aircraft/ATC-ML/Version (copy)"

git add Aircraft/ATC-ML/Version

git add Aircraft/DUMMY/

If you now perform the git status again you should see something similar to:

../GIT/fgdata$ git status
# On branch master.local
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#	modified:   Aircraft/ATC-ML/Version
#	new file:   Aircraft/ATC-ML/Version (copy)
#	new file:   Aircraft/DUMMY/ATC-ML (copy).xml
#	new file:   Aircraft/DUMMY/ATC-ML-set.xml
#	new file:   Aircraft/DUMMY/ATC-ML.ac
#	new file:   Aircraft/DUMMY/ATC-ML.nas
  ... etc.
#

If that is all you need - you may "commit" it:

"Commit"

git commit -m "your short, accompanying Announcement"

will commit the updates to the master.local branch. It shows a list compatible to the one created with the "git status" before, but this time this created something new! (Yes: You could have omitted the "git status" and just did the "commit" - but we suggest to "double-check" this way!)

git log

..GIT/fgdata$ git log
commit 7658c67c16a79900acf99dbfd85499b720dcc920
Author: YourName <Your eMail>
Date:   Mon Jun 4 19:14:29 2012 +0200
 
   your short, accompanying Announcement

This is the "commit" as it will be tracked within the GIT.

You definitely should now copy the ID (the first 8 digits may be enough) to use it later as a unique identifier!

Now return to your local "master" with:

git checkout master

git fetch git://gitorious.org/fg/fgdata.git

replace in that line the "fgdata.git" with the repository you are actually working on

this will update the master to the newest GIT-level (there may have been changes during all that time!)

git cherry-pick 7658c67c

replace the "7658c67c" with the first digits of your commit-ID (see above "git log")

will pull the commit into the "master"

git rebase origin/master

finally update the "master" with the "commit" on top of it

Push your changes to your clone on Gitorious

git push git@gitorious.org:~YourID/fg/YourIDs-fgdata.git

replace "YourID" with your login-name for Gitorious, do not forget the "~" in front of it!

replace in that line the "fgdata.git" with the repository you are actually working on

will finally push your updates to your space inside "gitorious.org"

Now you can announce to GIT that you have a change that may be merged into the original GIT:

• Open your git-clone on Gitorious: https://gitorious.org/~YourID/fg/YourID-fgdata
• and click the "Request merge" button on the right:

Creating a merge request at Gitorious.

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".

Commit the changes into the GIT

This step is for developers with fgdata commit access only!
See e.g. https://gitorious.org/+flightgear-developers/memberships
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

---

Supporting Informations

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!

git pull

may be used for future updates

Tracking a release branch

git branch -t -l release/2.6.0 origin/release/2.6.0
git checkout -b release/2.6.0

Git tutorials and resources

• Git documentation and tutorials
• Git Basics [1]
• 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