FlightGear Git: Difference between revisions

Jump to navigation Jump to search

FlightGear Git (view source)

Revision as of 09:49, 4 June 2012

2,981 bytes added ,  4 June 2012
m
(Still Updating, Part 3 till update repositories to come)
No edit summary
m ((Still Updating, Part 3 till update repositories to come))
Line 12: Line 12:
[[Howto:Start using git]] provides a quick introduction to using git.
[[Howto:Start using git]] provides a quick introduction to using git.


== Motivation ==
== '''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 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.
Line 21: Line 21:




== Manipulating the GIT ==
== '''Manipulating the GIT''' ==
=== Overview ===
=== Overview ===
{|
{|
Line 27: Line 27:
||For a detailed description see the description of the 4 repositories (A,B,C,D) in the following chapters
||For a detailed description see the description of the 4 repositories (A,B,C,D) in the following chapters
|}
|}
<br /><br />
=== A) Repositories and branches ===
=== 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 41: 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.
 
<br /><br />
=== B) Create your own workspace on Gitorious ===
=== 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
Prior to be able to manipulate GIT-data you must be a registered User and be logged in as such. See
Line 63: Line 64:
The created GIT-clone will be '''https://gitorious.org/~YourUID'''
The created GIT-clone 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>)
<small>''("YourUID" being your ID you logged in with, and do not forgett the "~" in front of it!)''</small>)
 
<br /><br />
=== C) Create a "master" on your local PC ===
=== C) Create a "master" on your local PC ===
''All the following is shown as performed in an UBUNTU "Terminal" environment! Please adapt especially the directory trees according to your Operating-System!''
''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 PC, e.g. "..'''\GIT'''"
# 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
# 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>)
#* ''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:
# use one of the following commands (or similar) from within that "..'''\GIT'''"-folder:
:*for cloning '''''SimGear''''' use:
:*for cloning '''''SimGear''''' use:
Line 81: Line 82:
::'''<nowiki>git clone git://gitorious.org/fg/fgdata.git</nowiki>''' [target]
::'''<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.: "simgear", "flightgear", "fgdata")''</small>.
: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]
'''<code>cd</code>''' into the new folder [target]
:You are now 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.
:You are now inside the ''working tree'' of this git repo. The repo itself is stored inside the subfolder <tt>../GIT/[target]/.git</tt>, which we mustn't 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>
;<code>git branch</code>
: will show the active [[FlightGear and Git#Repositories and Branches|branch]].  e.g.
: will show the active [[FlightGear and Git#Repositories and Branches|branch]].  e.g.
<small>
<small>
  ..GIT/fgdata$ git branch
  ..GIT/fgdata$ '''git branch'''
  * master
  * master
   master.local  <small>''(<-- this will not be there initially!)''</small>
   master.local  <small>''(<-- this branch will not be there initially!)''</small>
..GIT/fgdata$
:</small>Right after download the active GIT-repository-branch will be <tt>'''"next"'''</tt>, which on your PC 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.
:</small>Right after download this will be the GIT-repository-branch <tt>'''"next"'''</tt>, which on your PC 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>
;<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.:
: will list '''''all''''' branches of a git repository. The one marked with an asterisk (*) is the active one. e.g.:
<small>
<small>
  ..GIT/fgdata$ git branch -a
  ..GIT/fgdata$ '''git branch -a'''
  * master
  * master
   master.local  <small>''(<-- this will not be there initially!)''</small>
   master.local  <small>''(<-- this will not be there initially!)''</small>
Line 109: Line 110:
   remotes/origin/release/2.6.0
   remotes/origin/release/2.6.0
   remotes/origin/releases/2.2.0
   remotes/origin/releases/2.2.0
..GIT/fgdata$
</small>
</small>


You now have your local "GIT-master".
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 recommended to create a local branch inside that repository. In the chapter [[FlightGear and Git#D) Editing Data|D) Editing Data]] 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.  
'''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#D) Editing Data|D) Editing Data]]" 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.  
 
<br /><br />
==== Special for '''fgdata''':====
==== 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''' 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]].
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]].
Line 135: Line 135:


Do the following steps to extract the bundle and bring the repository up to date:
Do the following steps to extract the bundle and bring the repository up to date:
  $ git clone fgdata.bundle fgdata
<small>
  $ git '''clone fgdata.bundle fgdata'''
  $ cd fgdata
  $ cd fgdata
  $ git checkout -b master-tmp
  $ git checkout -b master-tmp
Line 145: Line 146:
  $ git checkout master
  $ git checkout master
  $ git branch -D master-tmp
  $ git branch -D master-tmp
</small>


If you get an error at '''<code>git fetch origin</code>''' try:
If you get an error at '''<code>git fetch origin</code>''' try:
<small>
  $ git remote rm origin
  $ git remote rm origin
  $ git remote add origin git://mapserver.flightgear.org/fgdata/
  $ git remote add origin git://mapserver.flightgear.org/fgdata/
  $ git fetch origin
  $ git fetch origin
</small>
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).
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).
 
<br /><br />
=== D) Editing Data ===
=== D) Editing Data ===
:;<code>git checkout master</code>
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:
:: 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 master</code>
:;<code>git checkout v2.0.0</code>
<small>
:: will activate the state of the code inside the <tt>master</tt> branch at the time FG 2.0.0 was released.
..GIT/fgdata$ '''git checkout master'''
 
Switched to branch 'master'
:;<code>git tag</code>
</small>
:: will show all tags of the history of the active branch.
: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
;<code>git pull</code>
<small>
: will update the local repo from the remote one.
GIT/fgdata$ '''git checkout master'''
 
Already on 'master'
 
Your branch is ahead of 'origin/master' by 2 commits.
one. You may now apply your individual stuff there and start FlightGear to verify the changes are proper.
</small>
 
:you need to resync your master with e.g.:
If you conclude they are, you have to tell git about those changes:
:;<code>git fetch</code>
<br />
;<code>git checkout -b master.local master</code>
<small>
..GIT/fgdata$ '''git checkout -b master.local master'''
Switched to a new branch 'master.local'
</small>
:Gnerates the new "master.local" and switches to it.
:In case you get the response
<small>
fatal: A branch named 'master.local' already exists.
</small>
::*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 />
You may now apply your planned changes and start FlightGear to verify they are proper.
<br />
If you conclude they are, have a look what was changed ''(the output may take some time to appear!)'':
<br />
;<code>git status</code>
;<code>git status</code>
: will give you a list of files that have been altered or that are new.
<small>
 
..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.
</small>
:will give you a list of files that have been altered or that are new. In 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
<br />
If that is what you wanted/needed continue with the following (otherwise correct your work first)
<br />
;<code>git add -i</code>
;<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''.
: 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''.
Line 176: Line 222:
: 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.
: 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.
: '''<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.
 
e.g.:
;<code>git commit</code>
<small>
: 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 committed your changes inside the ''working tree'' to your personal branch.
..GIT/fgdata$ '''git add -i'''
 
          staged    unstaged path
To update that personal branch from the remote one do the following steps:
  1:    unchanged        +1/-1 Aircraft/ATC-ML/Version
  git fetch                    # update repo
 
  git checkout master          # switch to master branch
*** Commands ***
git rebase origin/master      # update master branch
  1: [s]tatus   2: [u]pdate   3: [r]evert   4: [a]dd untracked
git checkout master.local    # switch back to the individual branch
  5: [p]atch   6: [d]iff   7: [q]uit   8: [h]elp
git rebase master            # update it
What now> a ''(⇐ will add the new parts)''
  1: Aircraft/ATC-ML/Version (copy)
  2: Aircraft/DUMMY/ATC-ML (copy).xml
  3: Aircraft/DUMMY/ATC-ML-set.xml
''(....etc.)''
Add untracked>> ''(⇐ just hit RETURN if nothing more is to be added!)''
 
*** Commands ***
  1: [s]tatus   2: [u]pdate   3: [r]evert   4: [a]dd untracked
  5: [p]atch   6: [d]iff   7: [q]uit   8: [h]elp
  What now> q
 
  Bye.
</small>
<br />
For updating all the repositories up to GIT see [[FlightGear and Git#Merge your Data into the GIT|Merge your Data into the GIT]]


=== Some more helpful commands ===
=== Some more helpful commands ===
Line 194: Line 255:
;<code>git checkout -f</code>
;<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>!
: 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>!
 
<br />
=== Tracking a release branch ===
=== Tracking a release branch ===
<pre>
<pre>
git branch -t -l release/2.6.0 origin/release/2.6.0
git branch -t -l release/2.6.0 origin/release/2.6.0
Line 202: Line 262:
</pre>
</pre>


For future updates just do a '''<code>git pull</code>'''.
<br /><br />
----
== '''Merge your Data into the GIT''' ==
=== Edit and "Commit" the changes ===
;<code>git commit</code>
: 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 committed your changes inside the ''working tree'' to your personal branch.


For future updates just do a '''<code>git pull</code>'''.
To update that personal branch from the remote one do the following steps:
git fetch                    # update repo
git checkout master          # switch to master branch
git rebase origin/master      # update master branch
git checkout master.local    # switch back to the individual branch
git rebase master            # update it
<br />


== Merge your Data into the GIT ==
=== 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:
 
<br /><br />
=== Rebase the master
=== 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/
 
<br /><br />
=== Push your changes to your clone on Gitorious ===
=== 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 222: Line 293:
: '''Source branch:''' master
: '''Source branch:''' master
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".
 
<br /><br />
== Commit the changes into the GIT ==
----
== '''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!'''


Line 233: Line 305:
  git cherry-pick b049e1d # repeat this for each commit you'd like to push
  git cherry-pick b049e1d # repeat this for each commit you'd like to push
  git push
  git push
 
<br /><br />
== External links ==
----
== '''External links''' ==
=== Git tutorials and resources ===
=== Git tutorials and resources ===
* Git [http://git-scm.com/documentation documentation and tutorials]
* Git [http://git-scm.com/documentation documentation and tutorials]
Jomo
652

edits

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

Navigation menu