FlightGear Git: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(→‎Repositories and branches: Add maclauncher link and fgms)
(23 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Git}}
{{Git}}
'''Git''' is a version control system, used by the [[FlightGear]] project to store all of the files required to build FlightGear. This includes all the programs, the data (e.g. [[aircraft]]), supporting tools, etc. Git tracks updates to every file, as developers from around the world work together concurrently to create new versions.
'''Git''' is a {{wikipedia|version control system}} used by the [[FlightGear]] project to store all the files required to build and run the simulator. This includes all the programs, the data (e.g. textures, sounds), supporting tools, etc. Git tracks updates to every file as developers from around the world work together concurrently to create new versions. The sole exception is the official [[FGAddon]] aircraft repository that is Subversion rather than Git based.


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.  
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 use the newest possible version of FlightGear from the latest source files, to experiment with new aircraft or other features. However, it is 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 its version control system from CVS to Git. The Git repositories are located at [http://gitorious.org/fg Gitorious] and a mirror is hosted at the [http://mapserver.flightgear.org/git/?p=fgdata;a=summary Mapserver].
As of May 2016, the repositories are located at {{Project infrastructure|name}}.


Due to the "recent" switch, we are currently doing our best on providing manuals for obtaining FlightGear through Git. The following articles belong to that "work in progress":
== Motivation ==
* [[FlightGear Git on Mac OS X]]
In May 2010, after a hardware failure on the [[CVS]] servers, the FlightGear project changed its version control system from CVS to Git.
* [[FlightGear Git on Windows]]
* [[Howto:Start using git]] provides a quick introduction to using a "source code management system"


== Motivation ==
Much has been written on the advantages of Git over CVS. For the FlightGear project, some advantages are:
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 work-flow.
* 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.
* 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.
* 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 ==
The FlightGear project is split up in the repositories listed below.
{| class="wikitable"
! Name
! Contents
! Remarks
|-
| {{simgear source|text=simgear}}
| The simulation engine that FlightGear uses.
| rowspan="6" |
Those repositories have the following branches:
* ''next'': current tip of new development. This branch should always compile and run, but various things could be broken.
* ''release/*'': containing former and (if a specific branch was made for them) upcoming releases.


== Manipulating the GIT ==
As of May 2016, FGRun is in the process of being replaced by the [[Qt5 Launcher|Qt5 launcher]].
=== Work-flow Overview===
|-
{|
| {{flightgear source|text=flightgear}}
||[[File:GIT-Workflow.png]]
| FlightGear itself.
|-
| {{fgdata source|text=fgdata}}
| All data (default aircraft, dialogs, sounds) used by FlightGear.
|-
| {{fgmeta source|text=fgmeta}}
| FlightGear "meta" repository containing build and setup scripts for the whole project.
|-
| {{windows-3rd-party source|text=windows-3rd-party}}
| Prebuilt libraries needed to make FlightGear run on Windows.
|-
| {{fgrun source|text=fgrun}}
| The [[FGRun]] launcher for FlightGear.
|-
| {{fgaddon source|text=fgaddon}}
| SVN repository that holds all official aircraft (except the [[Cessna 172P]] default plane and the [[UFO]]).
|
|-
| {{fgcom source|text=fgcom}}
| [[FGCom 3.0|FGCom]], a voice-over-IP application used by [[multiplayer]] controllers to provide [[Air traffic control|ATC services]].
|
|-
| {{getstart source|text=getstart}}
| Sources for the ''Getting Started'' manual included with the simulator.
|
|-
| {{openradar source|text=openradar}}
| The [[OpenRadar]] application used by multiplayer controllers.
|
|-
| {{sceneryweb source|text=sceneryweb}}
| Source code and configuration files for the [http://mapserver.flightgear.org/ Mapserver], the [https://scenery.flightgear.org/ scenery portal] and the [[TerraGear scenery build server]].
|
|-
| {{terragear source|text=terragear}}
| The [[TerraGear]] scenery building toolkit.
|
|-
| {{terrafs source|text=terrafs}}
| A Linux tool to mount the TerraSync scenery as a remote file system.
|
|-
| {{sourceforge source|proj=flightgear|repo=maclauncher|text=maclauncher}}
| Old FlightGear launcher for Mac.
| Deprecated by the [[Qt5 Launcher|Qt5 launcher]].
|-
| {{sourceforge source|proj=flightgear|repo=fgms|text=fgms}}
| Multiplayer server system
|
|}
|}
For a detailed description see the description of the four repositories (A,B,C,D) in the following chapters.
=== A) Repositories and branches ===
For historical reasons there continue to be separate repositories for [https://gitorious.org/fg/simgear '''''SimGear'''''] and [https://gitorious.org/fg/flightgear '''''FlightGear''''']. For most users and developers the most interesting ones for those 2 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 already defined one)'' upcoming releases.
For all available branches, see [https://gitorious.org/fg/simgear/trees SimGear branches] and/or [https://gitorious.org/fg/flightgear/trees FlightGear branches]
FlightGear [https://gitorious.org/fg/fgdata '''''data''''''] branches of interest are:
* '''''master''''': The one that is used with the '''''next''''' branch of the code.
* '''''release/*''''': The one that is used with the '''''release''''' branch of the code.
For all available branches see https://gitorious.org/fg/fgdata/trees
In addition, there's a '''fgmeta'' project, intended as a super-project to track compatible simgear & flightgear commits, particular in the context of release and stable branches. "fgmeta" contains the main repositories as git submodules:
* simgear
* flightgear
* fgrun
To work with the fgmeta project, you'll need to
* clone the fgmeta project: git://gitorious.org/fg/fgmeta.git
* run "git submodule init"
* run "git submodule update"
For other available projects have a look at our [http://gitorious.org/fg gitorious.org]. Use the "Source tree" button to see all available branches unique to those projects.
'''''Warning:'''''
* The "fgdata" project will be used in all following examples - thus the "Prime" local repository will always be named "master" (the '''code''' repositories like SimGear/FlightGear will usually use '''next''' instead of '''master''' however)!
* If you test changes, make sure all branches have the same status - otherwise your setup may not be functional!
=== 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''''' or '''''master''''' 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
The created GIT-clone will be on you private page '''https://gitorious.org/~<small>YourUID</small>'''
<small>''("YourUID" being your ID you logged in with, and do not forget the "~" in front of it!)''</small>)
=== C) Create a "master" on your local computer ===
''All the following is shown as performed in an UBUNTU "Terminal" environment! Please adapt especially the directory trees according to your Operating-System!''
# Create a unique folder on your computer, e.g. "..'''\GIT'''"
# Change into that folder and use the following "git clone" commands to clone the wanted repository
#* ''if you need/want more informations about unique GIT-commands, input "git help [command]"'' <small>(e.g. "git help clone")</small>
# Use one of the following commands (or similar) from within that "..'''\GIT'''"-folder:
:*for cloning '''''SimGear''''' use:
::'''<nowiki>git clone git://gitorious.org/fg/simgear.git</nowiki>''' [target]
::<small>To successfully compile <code>fgfs</code> Flight- and Sim-Gear's ''working tree'' they both must have the same state.</small>
:*for cloning '''''FlightGear''''' use:
::'''<nowiki>git clone git://gitorious.org/fg/flightgear.git</nowiki>''' [target]
::<small>To successfully compile <code>fgfs</code> Flight- and Sim-Gear's ''working tree'' they both must have the same state.</small>
:*for cloning '''''fgdata''''' use:
::'''<nowiki>git clone git://gitorious.org/fg/fgdata.git</nowiki>''' [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 <small>''(i.e.: "../GIT/simgear", "../GIT/flightgear", "../GIT/fgdata")''</small>.
'''<code>cd</code>''' into the new folder [target]
:You are now inside the ''working tree'' of this git repository. The repository itself is stored inside the subfolder <tt>../GIT/[target]/.git</tt>, which we must not edit manually. Git will take care of that.
:<small>Notice the "'''.'''" in front of the name: In Linux that indicates a hidden file, for which you might have to enable "show hidden files"!</small>
;<code>git branch</code>
: will show the active [[FlightGear_and_Git#A.29_Repositories_and_branches|branches]].  e.g.
..GIT/fgdata$ '''git branch'''
* master
  master.local  <small>''(<-- this branch will not be there initially!)''</small>
:Right after download the active GIT-repository-branch will be <tt>'''"next"'''</tt>, which in the example 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.
;<code>git branch -a</code>
: 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  <small>''(<-- this will not be there initially!)''</small>
  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 "[[FlightGear and Git#Edit|Edit]]" 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''' within git. Therefore, if you have a slow or unstable connection to the internet, it is recommended to download the [[FlightGear and Git#fgdata.bundle|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 <tt>"next"</tt> 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 [http://flightgear.org/mirrors.html mirrors].
==== fgdata.bundle ====
For the FlightGear-data there is a [http://www.kernel.org/pub/software/scm/git/docs/git-bundle.html git-bundle] (snapshot) [http://mxchange.org:23456/file?info_hash=%BF%FF%AB%0C%16%BF%8Eg%B8%A0%CFw%01%0A%5D%8F%3F%81%96y torrent] ([http://mxchange.org:23456/ tracker]; [http://flightgear.mxchange.org/pub/fgfs/fgdata.bundle.md5 md5]|[http://flightgear.mxchange.org/pub/fgfs/fgdata.bundle.sha1 sha1]|[http://flightgear.mxchange.org/pub/fgfs/fgdata.bundle.sha512 sha512]) available. This way you can resume interrupted downloads. After unpacking it only a comparatively small amount of data has to be transferred from the git server to synchronize your repository. See also the Develop sections in [[FlightGear Git on Windows]].
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 '''<code>git fetch origin</code>''' 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:
;<code>git checkout master</code>
..GIT/fgdata$ '''git checkout master'''
Switched to branch 'master'
:will change the active [[FlightGear and Git#Repositories and Branches|branch]] to <tt>master</tt>. 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 should re-sync your master with e.g.:
:;<code>git fetch</code>
;<code>git checkout -b master.local master</code>
..GIT/fgdata$ '''git checkout -b master.local master'''
Switched to a new branch 'master.local'
:Generates 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 - <span style="color:red">'''''even if there is uncommitted work in it !!'''''</span>
<br /><span style="color:green">
'''''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:'''''
</span>
;<code>git status</code>
:<small>the output may take some time to appear!</small>
: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:'''''
;<code>git add "Aircraft/ATC-ML/Version (copy)"</code>
;<code>git add Aircraft/ATC-ML/Version</code>
;<code>git add Aircraft/DUMMY/</code>
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"====
;<code>git commit -m "''your short, accompanying Announcement''"</code>
: 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 "git commit" created something new! ''(Yes: You could have omitted the "git status" and just did the "commit" - but we suggest to "double-check" it this way!)''
;<code>git log</code>
..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:
;<code>git checkout master</code>
;<code><nowiki>git fetch git://gitorious.org/fg/fgdata.git</nowiki></code>
:''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!)''
;<code>git cherry-pick 7658c67c</code>
:''replace the "7658c67c" with the first digits of your commit-ID (see above "git log")''
:will pull the commit into the "master"
;<code>git rebase origin/master</code>
:finally update the "master" with the "commit" on top of it
=== Push your changes to your clone on Gitorious ===
;<code>git push git@gitorious.org:~<small>YourUID</small>/fg/<small>YourUID</small>s-fgdata.git</code>
<small>
::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
</small>
: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/~<small>YourUID</small>/fg/<small>YourUID</small>-fgdata
*and click the "Request merge" button on the right:
[[File:Create merge request at Gitorious.png|thumb|270px|Creating a merge request at Gitorious.]]
Write a short summary, in which you explain what your commit(s) do(es). Then choose the following settings:
: '''Target directory:''' fgdata, flightgear or simgear
: '''Target branch:''' master, next or whatever
: '''Source branch:''' master, next or whatever
Next select the commits you would like to include in your merge request and click "Create merge request".
Note that it usually doesn't suffice to just send a merge request via gitorious (unfortunately), but that you'll often also need to "ping" 1-3 core developers who have previously worked with the subsystems affected by the patch (and send a reminder once in a while).
It makes sense to watch the forums/mailing lists or just the git history to see which developers are currently active. To get a list of people who have previously worked with the affected subsystems/files, just take a look at the commit log of the corresponding files and get in touch with the developers via the devel list or forum.
Also, it may help to send a follow-up (merge request review) via the issue tracker here: https://code.google.com/p/flightgear-bugs/issues/entry?template=Review%20request
Currently, it isn't uncommon for merge requests to take 2-4 weeks, and sometimes even 1-2 months before being reviewed and committed. Your chances of getting your code committed upstream are much better directly after a release, than shortly before a release obviously (feature freeze).
=== Commit the changes into the GIT ===
<span style="color:red">'''''This step is for developers with fgdata commit access only!'''''</span>
For a list of those authorized see: https://gitorious.org/+flightgear-developers/memberships and http://gitorious.org/+fgdata-developers/memberships (fgdata only)
To push a merge request to fgdata, the following work-flow can be followed:
{{pre2|scroll|
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}}


== Related content ==
== Related content ==
* [[FlightGear Git: splitting fgdata]], an initiative to split the aircraft out of the fgdata repository, in order to decrease its size and thus improve access to the average user/developer.
* [[FlightGear Git: splitting FGData]], an initiative to split the aircraft out of the FGData repository, in order to decrease its size and thus improve access to the average user/developer.


{{Building}}
{{Building}}

Revision as of 13:55, 20 November 2016

Git is a version control system This is a link to a Wikipedia article used by the FlightGear project to store all the files required to build and run the simulator. This includes all the programs, the data (e.g. textures, sounds), supporting tools, etc. Git tracks updates to every file as developers from around the world work together concurrently to create new versions. The sole exception is the official FGAddon aircraft repository that is Subversion rather than Git based.

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 use the newest possible version of FlightGear from the latest source files, to experiment with new aircraft or other features. However, it is not a beginner's tool. Using Git can expose the user to unstable features that show ugly error messages, or crash the computer.

As of May 2016, the repositories are located at SourceForge.

Motivation

In May 2010, after a hardware failure on the CVS servers, the FlightGear project changed its version control system from CVS to Git.

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.

Repositories and branches

The FlightGear project is split up in the repositories listed below.

Name Contents Remarks
simgear The simulation engine that FlightGear uses.

Those repositories have the following branches:

  • next: current tip of new development. This branch should always compile and run, but various things could be broken.
  • release/*: containing former and (if a specific branch was made for them) upcoming releases.

As of May 2016, FGRun is in the process of being replaced by the Qt5 launcher.

flightgear FlightGear itself.
fgdata All data (default aircraft, dialogs, sounds) used by FlightGear.
fgmeta FlightGear "meta" repository containing build and setup scripts for the whole project.
windows-3rd-party Prebuilt libraries needed to make FlightGear run on Windows.
fgrun The FGRun launcher for FlightGear.
fgaddon SVN repository that holds all official aircraft (except the Cessna 172P default plane and the UFO).
fgcom FGCom, a voice-over-IP application used by multiplayer controllers to provide ATC services.
getstart Sources for the Getting Started manual included with the simulator.
openradar The OpenRadar application used by multiplayer controllers.
sceneryweb Source code and configuration files for the Mapserver, the scenery portal and the TerraGear scenery build server.
terragear The TerraGear scenery building toolkit.
terrafs A Linux tool to mount the TerraSync scenery as a remote file system.
maclauncher Old FlightGear launcher for Mac. Deprecated by the Qt5 launcher.
fgms Multiplayer server system

Related content

  • FlightGear Git: splitting FGData, an initiative to split the aircraft out of the FGData repository, in order to decrease its size and thus improve access to the average user/developer.