FlightGear Git: Difference between revisions

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.  

* [[FlightGear Git on Windows]]

* [[Howto:Start using git]] provides a quick introduction to using a "source code management system"

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.

Also, as noted before, the CVS servers had a hardware failure on May 2010, speeding up FlightGear's change to Git.

=== Work-flow Overview===

{|

||[[File:GIT-Workflow.png]]

|}

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

* '''''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

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:'''''  

=== B) Create your own workspace on Gitorious ===

: https://gitorious.org/users/new  

: https://gitorious.org/login

* getstart

* etc.

* assist with reporting bugs before they are released as a proper release version

* or participate in the design

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

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

#* ''if you need/want more informations about unique GIT-commands, input "git help [command]"'' <small>(e.g. "git help clone")</small>

:*for cloning '''''SimGear''''' use:

::'''<nowiki>git clone git://gitorious.org/fg/simgear.git</nowiki>''' [target]

'''<code>cd</code>''' into the new folder [target]

:<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

;<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

   remotes/origin/release/2.6.0

   remotes/origin/releases/2.2.0

You now have your local "GIT-master".

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

Do the following steps to extract the bundle and bring the repository up to date:

  $ git '''clone fgdata.bundle fgdata'''

  $ cd fgdata

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

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

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

::*you have to define another name for that branch

::*or delete it:

*start FlightGear to verify they are proper/functional

*then check what was done:'''''

;<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

  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/DUMMY/</code>

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

  ../GIT/fgdata$ ''git status''

  # On branch master.local

   ''... etc.''

  #

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

===="Commit"====

;<code>git commit -m "''your short, accompanying Announcement''"</code>

;<code>git log</code>

  ..GIT/fgdata$ git log

  commit 7658c67c16a79900acf99dbfd85499b720dcc920

    

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

*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:

<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  

To push a merge request to fgdata, the following work-flow 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

=== Some more helpful commands ===

;<code>git help</code>

;<code>git pull</code>'''

: may be used for future updates

=== Tracking a release branch ===

=== Git tutorials and resources ===

* Git [http://git-scm.com/documentation documentation and tutorials]

* [http://sourceforge.net/projects/qgit qgit - interactive git repository viewer and frontend]

* Additional [[Resources WRT running git on Win32]]

{{Building}}

[[Category:Core developer documentation]]

[[Category:FlightGear]]

[[fr:FlightGear et Git]]