FlightGear Git: data developers

Anyone contributing data to FlightGear, like aircraft models, dialogs or textures, is a data developer. This article helps those in setting up a correct workflow, to ease the inclusion of their work into the simulator.

Note about aircraft

As of September 2014, all aircraft excluding the Cessna 172P and the UFO (shipped by default with FlightGear, both being still part of fgdata) have been migrated into the FGAddon SVN repository.

Preparations

The steps described in this section are only required once, at the initialization of your development environment.

Cloning the repository

The first thing to do as a prospective developer is to register at SourceForge if you haven't already done so. This will enable you to publish your edits and have them incorporated into the main project.

After logging in, you can create a personal "clone" of the data repository. This clone is where you will be working in, without touching the main repository. To create a clone, navigate to the fgdata repository on flightgear/fgdata/next and click the Fork button. In general the default name is fine, but you can change it to whatever you like. SourceForge will now clone the data repository. Due to the size of our repository, this can take some time.

Obtaining the data

Before you can start editing, you first need to retrieve the data to your computer. As of March 2015, the size of the fgdata repository is about 1.3 GB. There are four ways to do this.

For all approaches, Git must be installed. There is a lot of software available, but the following are often used:

• Microsoft Windows: Git for Windows
• OS X: Git for OSX

Single clone

1. Create a directory on your computer where you will be storing the data.
2. Run/Open the GIT command editor (GIT CMD or GIT GUI in Windows Start Menu) and navigate to that folder.
3. Clone the repository with the following command. This will create a /fgdata subfolder and put all the contents of the repository in there.

   git clone git://git.code.sf.net/p/flightgear/fgdata/

Note  Continuing an interrupted cloning of a repository is not supported within Git. If you can not complete cloning due to connection issues, use one of the alternative methods below.

Cloning using a boilerplate tarball

This method for cloning FGData works by initially downloading a boilerplate tarball (a copy of the FGData repository) via HTTP, which supports resuming a partial/interrupted download, and then bringing it up to date to get the latest changes.

1. Create a directory on your computer where you will be storing the data.
2. Download the FGData boilerplate tarball.
3. Run/Open the GIT command editor (GIT CMD or GIT GUI in Windows Start Menu) and navigate to the directory you created in point 1.
4. Uncompress the FGData boilerplate tarball in that directory. On Windows, you can use a file archiver like 7-Zip. On OS X and Linux, you can issue the following command:

$ tar xvf path-to-boilerplate-tarball

where path-to-boilerplate-tarball is the path to the file you downloaded in step 2.

5. Fetch the latest changes in the Git repository by running:

$ git pull

6. Check out the files to get the updated copy of FGData:

$ git checkout -- .

Cloning using BitTorrent

Like the "boilerplate tarball" mentioned above, this method initially fetches a Git bundle (snapshot) of the FGData repository over a method that supports resuming an interrupted download (namely, BitTorrent), then brings it up to date.

1. Create a directory on your computer where you will be storing the data.
2. Download the FGData bundle from this tracker using your favorite BitTorrent client.

Note  The download may be slow as there usually are only a few seeders. When you finish downloading the file, consider leaving your BitTorrent client open to seed it further.

3. Run/Open the GIT command editor (GIT CMD or GIT GUI in Windows Start Menu) and navigate to the directory you created in step 1.
4. Issue the following commands to extract the bundle and bring the repository up to date:

$ git clone fgdata.bundle .
$ git checkout -b master-tmp
$ git remote rm origin
$ git remote add origin git://git.code.sf.net/p/flightgear/fgdata
$ git fetch origin
$ git branch --track next origin/next
$ git checkout next
$ git branch -D master-tmp

Cloning by getting a few commits at a time

This method works by initially retrieving only the latest revision of FGData and then getting a few previous commits at a time.

1. Create a directory on your computer where you will be storing the data.
2. Run/Open the GIT command editor (GIT CMD or GIT GUI in Windows Start Menu) and navigate to that folder.
3. Clone the repository with the following command. This will create a /fgdata subfolder and put all the contents of the repository in there.

   git clone git://git.code.sf.net/p/flightgear/fgdata/ --depth=1

4. Once the initial retrieval is performed, fetch previous commits one hundred at a time:

   git fetch --depth=n

   Start by replacing n with 100 and continue executing the previous command, increasing n by 100 each time, until Git outputs the message Already up to date.

5. Convert the repository to a complete one:

$ git fetch --unshallow

Authentication

In order to publish edits on SourceForge, you need to generate a secret key so you can be correctly identified.

1. Navigate to your newly created fgdata directory and run:

   ssh-keygen

   or, if using GIT CMD in windows: git -c alias.ssh-keygen=!ssh-keygen ssh-keygen

2. Enter the name of the file in which you prefer to save the key and press Enter.
3. Enter your password/passphrase and press Enter. You'll have to do this twice.
4. Your key is now being generated. Open the .pub file with an editor and copy the content.
5. Visit your account settings at SourceForge and navigate to "SSH settings".
6. Paste the content of the .pub file and press "Save".
7. Now run the following, again in your fgdata directory, with <url> as the line that you get by clicking RW on your fgdata clone page at SourceForge (something like ssh://~you-user-name~@git.code.sf.net/u/~you-user-name~/flightgear/):

   git remote set-url origin <url>

Obtaining the simulator

In order to test your work, you'll need the FlightGear version that matches the data. Since FlightGear is under constant development, data from Git does not work with previous releases - e.g. preview or LTS. Fortunately obtaining the latest development version of the simulator is fairly straightforward for most operating systems.

• Mac: Download the .dmg. Also at builds/nightly/ (Nov 2021) - download the small *.dmg.
• Windows: Download the 32-bits or 64-bits .exe installer and follow its instructions. Also at builds/nightly/ (Nov 2021) - download the small *.exe. Let it install the binary into a clean directory.

Point $FG_ROOT to your freshly obtained fgdata directory. When using the command line: set $FG_ROOT via --fg-root=path/to/root - on Windows this can be added to a shortcut to the development version. When using the launcher: select a directory from '...' menu > Select data files location > and follow instructions. You can use multiple installs of FlightGear in parallel.

Making edits

It is recommended to split your new fgdata clone into separate local branches for your work. For instance, if you're working on the Boeing 747-400 and the aircraft reflection shader, you might create 2 branches named "747-400" and "reflect-shader". To do this, run the following commands:

git checkout master

git checkout -b <branch name>

Then you can make your changes to the new local branch(es), which will make merge requests easier for both yourself and committers. To switch in between branches, simply use

git checkout <branch name>

Publishing edits

To push local updates to your fgdata clone on SourceForge, perform the following steps:

1. Switch to the branch that contains your edits:

   git checkout <branch name>

2. List all the changed files:

   git status -- .

3. Now it's time to commit the changed files.
   • If you want to commit all changed files, run the following and type your commit message.

     git commit -a

   • If you only want to commit a selection of files, run the following:

     git add <path/to/file> (for single files)

     git add --all <path/to/folder> (to add all files within a certain folder)

     git rm <path/to/file> (to remove files that you've removed)

   Followed by

   git commit -m "<commit message>"

4. Check if everything went fine, by loading Gitk:

   gitk

5. Finally, push the commit to your fgdata clone SourceForge with the following command. Replace YourUID with your SourceForge account. Make sure you have correctly set up the clone as the origin as described under #Authentication.

   git push

Requesting edits to be merged

1. Click the "Request merge" button on your fgdata clone page. Loading the next page can take a while, as it will list all commits of the past years!
2. Once again write a short summary (could be the same as used with git commit), but this time, also write an explanation of your merge request (what does it do?). Make sure you set the target repository to fgdata, target branch to next and source branch to the local branch with your updates.
3. Tick the box in front of your commit and click the "Create merge request" button.
4. Everyone can see the pending request, but in order to make sure that your request gets looked at, you may contact a contributor.

Creating merge requests using this method literally means merging an entire branch into fgdata; this may not be desirable for some situations, such as small changes that only require one little commit. There's a neat method to only push certain commits to a merge request discussed by Anders Gidenstam on the FlightGear Forums.

References