FlightGear Git: Difference between revisions

Jump to navigation Jump to search

FlightGear Git (view source)

Revision as of 08:11, 1 June 2012

1,247 bytes added ,  1 June 2012
General review to try making it simpler for "newbies in design". Part 1 = up to creating local master --> will be continued
(General review to try making it simpler for "newbies in design". Part 1 = up to creating local master --> will be continued)
Line 1: Line 1:
{{FlightGearGitOn}}
{{FlightGearGitOn}}
'''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 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.  
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.  
Line 20: Line 20:
Also, as noted before, the CVS servers had a hardware failure on May 2010, speeding up FlightGear's change to Git.
Also, as noted before, the CVS servers had a hardware failure on May 2010, speeding up FlightGear's change to Git.


== Repositories and branches ==
 
== Manipulating the GIT ==
=== Overview ===
{|
||[[File:GIT-Workflow.png|center|Cloning and manipulating the GIT]]
||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:
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:


Line 35: Line 42:
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.
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 ==
=== B) Create your own workspace on Gitorious ===
=== Quick checkout ===
Prior to be able to manipulate GIT-data you must be a registered User and be logged in as such. See
# Check on gitorious for valid projects: http://gitorious.org/fg
: https://gitorious.org/users/new
# Cloning Simgear
: https://gitorious.org/login
# Cloning FlightGear
 
# Cloning FGData
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 space to work in)'' by activating the "Clone repository" button of the wanted project.
 
By default you will be cloning the <tt>next</tt> branch of SimGear and FlightGear and the <tt>master</tt> branch of FGData. 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".


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.
The created GIT-cone will be '''https://gitorious.org/~YourUID'''
<small>''("YourUID" being your ID you logged in with, and do not forgett the "~" in front of it!)''</small)


=== For dummies ===
=== C) Create a "master" on your local PC ===
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.
# Create a unique folder on your PC, e.g. "..'''\GIT'''"
# change into that folder and use the "git clone" commands to clone the wanted repository
## ''if you need/want more informations about those 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:


==== Cloning SimGear ====
==== Cloning SimGear ====
Line 85: Line 109:
'''<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>'''.
'''<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>'''.


==== Local branch ====
==== 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 '''<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) Editing Data  ===
To make individual changes, like editing a [[joystick]] file, 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.
To make individual changes, like editing a [[joystick]] file, 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.


Line 111: Line 166:
  git rebase master            # update it
  git rebase master            # update it


==== Some more helpful commands ====
=== Some more helpful commands ===
;<code>git help</code>
;<code>git help</code>
;<code>git help [commad]</code>
;<code>git help [commad]</code>
Line 119: Line 174:
: 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>!
: 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>!


==== Tracking a release branch ====
=== Tracking a release branch ===


<pre>
<pre>
Line 126: Line 181:
</pre>
</pre>


=== 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 '''<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>'''.
For future updates just do a '''<code>git pull</code>'''.


== Merge requests ==
== Merge your Data into the GIT ==
=== Create ===
=== Edit and "Commit" the changes ===
[[File:Create merge request at Gitorious.png|thumb|270px|Creating a merge request at Gitorious.]]
[[File:Create merge request at Gitorious.png|thumb|270px|Creating a merge request at Gitorious.]]
Make a clone of fgdata, by clicking the [https://gitorious.org/fg/fgdata/clone clone repository] button on Gitorious. Commit your stuff first to your local repository (git commit), then perform the following commands:
Make a clone of fgdata, by clicking the [https://gitorious.org/fg/fgdata/clone clone repository] button on Gitorious. Commit your stuff first to your local repository (git commit), then perform the following commands:


=== Rebase the master
* <code>git fetch</code> to get the latest commits from fgdata/
* <code>git fetch</code> to get the latest commits from fgdata/
* <code>git rebase origin/master</code> place your own commit on top of the latest commits/
* <code>git rebase origin/master</code> place your own commit on top of the latest commits/
=== Push your changes to your clone on Gitorious ===
* <code>git push git@gitorious.org:~name/fg/namess-fgdata.git</code> push your commits to your fgdata clone. Replace the url with your fgdata-clone's SSH url!
* <code>git push git@gitorious.org:~name/fg/namess-fgdata.git</code> push your commits to your fgdata clone. Replace the url with your fgdata-clone's SSH url!


Line 173: Line 202:
Next select the commits you'd like to include in your merge request and click "Create merge request".
Next select the commits you'd like to include in your merge request and click "Create merge request".


=== Push/merge ===
== Commit the changes into the GIT ==
'''This step is for developers with fgdata commit access only!'''
'''This step is for developers with fgdata commit access only!'''


Jomo
652

edits

Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/50718"

Navigation menu