FlightGear Git: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(→‎fgdata.bundle: updated instructions for new bundle version)
m (Update link to FR page)
 
(72 intermediate revisions by 18 users not shown)
Line 1: Line 1:
{{FlightGearGitOn}}
{{Git}}
'''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.  
'''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 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.  
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 version control system from CVS to Git. The Git repositories are located at [http://gitorious.org/fg Gitorious] and 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 are work in progress:
== Motivation ==
* '''Mac OS X:''' [[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.
* '''Windows:''' [[FlightGear Git on Windows]]


== 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 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.
* 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 ==
 
{{Note|
 
Next is C++17 since we branched 2020.3 off: so far this seems to be working well, we can use the fun stuff such as std::optional, and the nicer overloads of make_shared / make_unique. Since 2020.3 and before also used C++11, we have been using lambdas, direct member init and gradually replacing ‘typedef’ with ‘using’ for years now, but as an incremental process: for the time being, it doesn't seem like wholesale search and replace conversions are justified.<ref>https://sourceforge.net/p/flightgear/mailman/message/37309892/</ref>
== 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:
The FlightGear project is split up in the repositories listed below.
 
{| class="wikitable"
* <tt>next</tt> The current tip of new development. This branch should always compile and run, but various things could be broken.
! Name
* <tt>release/*</tt> The branch subdirectory containing former and, if there is one, upcoming releases.
! Contents
For other available branches have a look at our [http://gitorious.org/fg/flightgear#more repository] at gitorious.org. The following two branches are as of now (May 2011) very much out of date. '''Do not use'''.
! Remarks
* <tt>master</tt> 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 <tt>next</tt> branch for a few days or weeks will be merged here.
|-
* <tt>maint</tt> Bug fixes for the most recently released Flightgear. When a release is made from <tt>master</tt>, this branch is reset to it.
| {{simgear source|text=simgear}}
 
| [[SimGear]], the simulation engine that FlightGear uses.
 
| rowspan="6" |
FlightGear '''data''''s branches of interest are:
Those repositories have the following branches:
* <tt>master</tt> The one that is used with the <tt>next</tt> branch of the source.
* ''next'': current tip of new development. This branch should always compile and run, but various things could be broken.
* <tt>release/*</tt> Same as for the source.
* ''release/*'': containing former and (if a specific branch was made for them) upcoming releases.
 
 
This arrangement follows the scheme used by the Git maintainers.
[http://www.kernel.org/pub/software/scm/git/docs/howto/maintain-git.txt 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 ===
# Check on gitorious for valid projects: http://gitorious.org/fg
# Cloning Simgear
# Cloning FlightGear
# Cloning FGData
 
By default you will be checking out the <tt>next</tt> branch of SimGear and FlightGear and the <tt>master</tt> 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.
 
 
=== 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.<br />
 
==== Cloning SimGear ====
;<code>git clone git://gitorious.org/fg/simgear.git [target]</code>
: 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 <code>simgear</code>.
 
'''<code>cd</code>''' into the new folder. You are then inside the ''working tree'' of this git repo. The repo itself is stored inside the subfolder <tt>.git</tt>, which we mustn't edit manually. Git will take care of that.
 
;<code>git branch</code>
: will show the active [[FlightGear and Git#Repositories and Branches|branch]]. Right after download this will be <tt>* next</tt>, that means the content of the ''working tree'' is the bleeding edge of SimGear's 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.
 
;<code>git checkout master</code>
: 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.
 
:;<code>git checkout v2.0.0</code>
:: will activate the state of the code inside the <tt>master</tt> branch at the time FG 2.0.0 was released.
:;<code>git tag</code>
:: will show all tags of the history of the active branch.
 
;<code>git pull</code>
: will update the local repo from the remote one.
 
 
==== Cloning FlightGear ====
Except for the initial clone command this is identic to [[FlightGear and Git#Cloning SimGear|Cloning SimGear]].
;<code>git clone git://gitorious.org/fg/flightgear.git [target]</code>
To successfully compile <code>fgfs</code> Flight- and SimGear's ''working tree'' must have the same state.
 
 
==== Cloning 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 [[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 you want to build FlightGear 2.0.0 you may fetch the data (FlightGear-data-2.0.0.tar.bz2) at one of the [http://flightgear.org/mirrors.html mirrors].
People not interested in actively contributing to C++ development are encouraged to use the release/2020.3 branch as the next branch may undergoing significant breakage in the near term future.


;<code>git clone git://mapserver.flightgear.org/fgdata/ [target]</code>
As of [[Changelog 2016.1#Usability|May 2016]], FGRun is replaced by the [[Qt5 Launcher|Qt5 launcher]].
: if no ''target'' is given the new folder's name is <tt>fgdata</tt>
|-
'''<code>cd</code>''' into the new directory and verify it's state with '''<code>git branch</code>'''. If it isn't <tt>* master</tt>, do a '''<code>git checkout master</code>'''.
| {{flightgear source|text=flightgear}}
 
| FlightGear itself.
 
|-
==== Local Branch ====
| {{fgdata source|text=fgdata}}
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.
| All data (default aircraft, dialogs, sounds) used by FlightGear.
 
|-
'''<code>cd</code>''' into the repositories folder, e.g. fgdata:
| {{fgmeta source|text=fgmeta}}
;<code>git checkout -b master.local master</code>
| FlightGear "meta" repository containing build and setup scripts for the whole project.
: a new branch <tt>master.local</tt> is created out of the <tt>master</tt> branch and set as the active one. You may now apply your individual stuff there and start FlightGear to verify the changes are propper.
|-
 
| {{windows-3rd-party source|text=windows-3rd-party}}
If you conclude they are, you have to tell git about those changes:
| Prebuilt libraries needed to make FlightGear run on Windows.
;<code>git status</code>
|-
: will give you a list of files that have been altered or that are new.
| {{fgrun source|text=fgrun}}
 
| The [[FGRun]] launcher for FlightGear.
;<code>git add -i</code>
|-
: will show the files that have been altered and give you options on what to do next. <code>git add</code> does not actually add the changes to ''master.local'' but adds them to the ''index''.
| {{fgaddon source|text=fgaddon}}
: '''<tt>[a]dd</tt>''' 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''.
| [[FGAddon]], an SVN repository that holds all official aircraft (except the [[Cessna 172P]] default plane and the [[UFO]]).
: 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 [http://www.kernel.org/pub/software/scm/git/docs/git-add.html man git add] for more details.
|
: '''<tt>[u]pdate</tt>''' is the next step and will update the altered and ''tracked'' files to the index in the same manner as explained in <tt>add</tt> untracked paths above.
|-
;<code>git commit</code>
| {{fgcom source|text=fgcom}}
: 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 commited your changes inside the ''working tree'' to your personal branch.
| [[FGCom 3.0|FGCom]], a voice-over-IP application used by [[multiplayer]] controllers to provide [[Air traffic control|ATC services]].
 
|
To update that personal branch from the remote one do the following steps:
|-
git checkout master          # switch to master branch
| {{getstart source|text=getstart}}
git pull                      # update it
| Sources for the ''Getting Started'' manual included with the simulator.
git checkout master.local    # switch back to the individual branch
|
git rebase master            # update it
|-
 
| {{openradar source|text=openradar}}
 
| The [[OpenRadar]] application used by multiplayer controllers.
==== Some more helpful commands ====
|
;<code>git help</code>
|-
;<code>git help [commad]</code>
| {{sceneryweb source|text=sceneryweb}}
;<code>git apply</code>
| 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]].
: apply a patch to files and/or to the index http://www.kernel.org/pub/software/scm/git/docs/git-apply.html
|
;<code>git checkout -f</code>
|-
: may be used to throw away any local changes to the ''working tree''. Use with care, as any option that name is <tt>-f</tt> or <tt>--force</tt>, and only after reading <code>git checkout help</code>!
| {{terragear source|text=terragear}}
 
| The [[TerraGear]] scenery building toolkit.
 
|
=== 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.
| {{terrafs source|text=terrafs}}
 
| [[TerraFS]], a Linux tool to mount the TerraSync scenery as a remote file system.
Download the bundle from
|
$ wget http://flightgear.mxchange.org/pub/fgfs/fgdata.bundle
|-
 
| {{sourceforge source|proj=flightgear|repo=maclauncher|text=maclauncher}}
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-05-27 is 3607494099, while the md5 checksum is
| [[FlightGear_Mac_OS_X_Launcher|Old FlightGear launcher for Mac]].
$ md5sum fgdata.bundle
| Deprecated by the [[Qt5 Launcher]].
3ddb025053fc395323ae708816555551  fgdata.bundle
|-
 
| {{sourceforge source|proj=flightgear|repo=fgms|text=fgms}}
Do the following steps to extract the bundle and bring the repository up to date:
| [[FlightGear Multiplayer Server|Multiplayer server system]]
$ 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 '''<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).
 
For future updates just do a '''<code>git pull</code>'''.
 
== External links ==
=== Git tutorials and resources ===
* Git [http://git-scm.com/documentation documentation and tutorials]
* Git as a [http://tomayko.com/topics/git way of life].
* The [https://git.wiki.kernel.org/index.php/GitCheatSheet Git Cheat Sheet] and the [http://jan-krueger.net/development/git-cheat-sheet-extended-edition Git Cheat Sheet Extended Edition]
* [http://wiki.github.com/bogolisk/egg Egg], a cool Git emacs mode.
* A guide to [http://nathanj.github.com/gitguide/ using Git on Windows]
* [http://kylecordes.com/2008/04/30/git-windows-go/ Git on Windows Go!] (Setting up msysgit on Windows)
* [http://gitcasts.com/posts/git-on-windows Git on Windows (webcast)]
* [http://sourceforge.net/projects/qgit qgit - interactive git repository viewer and frontend]
* Additional [[Resources WRT running git on Win32]]


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


{{Building}}
{{Building}}


[[Category:Core developer documentation]]
[[Category:FlightGear]]
[[Category:FlightGear]]
[[Category:Git]]
[[fr:FlightGear Git]]

Latest revision as of 17:16, 21 December 2022

Git

Git is a version control system, used to store all files required to build FlightGear.

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

Note 

Next is C++17 since we branched 2020.3 off: so far this seems to be working well, we can use the fun stuff such as std::optional, and the nicer overloads of make_shared / make_unique. Since 2020.3 and before also used C++11, we have been using lambdas, direct member init and gradually replacing ‘typedef’ with ‘using’ for years now, but as an incremental process: for the time being, it doesn't seem like wholesale search and replace conversions are justified.[1]

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

Name Contents Remarks
simgear 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.

People not interested in actively contributing to C++ development are encouraged to use the release/2020.3 branch as the next branch may undergoing significant breakage in the near term future.

As of May 2016, FGRun is 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 FGAddon, an 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 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.
Building/Compiling
FlightGear
TerraGear
Related
  1. ↑ https://sourceforge.net/p/flightgear/mailman/message/37309892/
Retrieved from "https://wiki.flightgear.org/w/index.php?title=FlightGear_Git&oldid=136757"