652
edits
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 | #* ''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> | ||
:</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 | |||
;<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 | ||
</small> | </small> | ||
You now have your local "GIT-master". | You now have your local "GIT-master". | ||
'''But:''' To make individual 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: | ||
;<code>git checkout master</code> | |||
: | <small> | ||
: | ..GIT/fgdata$ '''git checkout master''' | ||
Switched to branch 'master' | |||
:;<code>git | </small> | ||
: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 | <small> | ||
: | GIT/fgdata$ '''git checkout master''' | ||
Already on 'master' | |||
Your branch is ahead of 'origin/master' by 2 commits. | |||
</small> | |||
:you need to resync your master with e.g.: | |||
If you conclude they are, | :;<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.: | |||
<small> | |||
: | ..GIT/fgdata$ '''git add -i''' | ||
staged unstaged path | |||
1: unchanged +1/-1 Aircraft/ATC-ML/Version | |||
*** 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> 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. | |||
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 /> | |||
[[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] |
edits