FlightGear Git for laymen: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
No edit summary
(→‎Step 2: Removed the Gitorious text and switched to {{fgdata clone}} for the git clone command.)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Git for Laymen =
Git, and its fellow {{Wikipedia|List of revision control software|version control systems}} are a domain of geeks who are patently incapable of explaining anything in simple terms most of the time. Because of this, many a layman has fled in terror from what is, when all's said and done, easy to use.
Git, and its fellow Version Control Systems are a domain of geeks - who are patently incapable of explaining anything in simple terms most of the time. Because of this, many a layman has fled in terror from what is, when all's said and done, easy to use.


== What is Git? ==
== What is Git? ==
Git is a Version Control System, meaning that it ''tracks changes to files'' - in other words, if you make a change to a file known to Git, or ''commit'' the change as the expert would put it, Git stores what parts of the file have changed between the last version and the current version. That makes it possible to do a lot of great things, the most mind-soothing among them being the ability to get the old version back in case it turns out you've broken something.
Git is a {{Wikipedia|distributed version control system}} (DVCS), meaning that it ''tracks changes to files'' in other words, if you make a change to a file known to Git, or ''commit'' the change as the expert would put it, Git stores what parts of the file have changed between the last version and the current version. That makes it possible to do a lot of great things, the most mind-soothing among them being the ability to get the old version back in case it turns out you've broken something.


== What does Git do for me? ==  
== What does Git do for me? ==  
Another thing Git does is ''distribute change''. That means, additionally to committing things ''to'' the Git repository, you can also get the changes others made ''from'' the Git repository - thus keeping your local copy of whatever is kept in the repository current. That is the use most laymen will be most interested in. In practical terms, that means you can at any time get all the changes the developers made just by updating your copy from the repository - instead of having to re-download the whole data (or trying to scrape together the changed files manually, a path that leads to insanity without any stop signs or speed limits). With a large repository like Flightgear Base Data for example, the difference is a few kilobytes instead of 15 gigabytes.
Another thing Git does is ''distribute change''. That means, additionally to committing things ''to'' the Git repository, you can also get the changes others made ''from'' the Git repository thus keeping your local copy of whatever is kept in the repository current. That is the use most laymen will be most interested in. In practical terms, that means you can at any time get all the changes the developers made just by updating your copy from the repository - instead of having to re-download the whole data (or trying to scrape together the changed files manually, a path that leads to insanity without any stop signs or speed limits). With a large repository like the FlightGear [[base package]] for example, the difference is a few kilobytes instead of 15 gigabytes.


== What do I need to use a Git repository that way? ==
== What do I need to use a Git repository that way? ==
Basicly, all you have to do is install a git client on your machine. For windows users, '''TrotoiseGit''', which is free for download, would be the option of choice, for Linux/Unix users it's just plain '''git''', available from your favorite software repository. Both are rather trivial to set up - the only confusing thing is that they may require you to supply a name and an email adress on install - don't get panicky, it's just a prerequisite Git has for use cases you'll never see unless you decide to come to the geek side of life. Needs to be done, just like you have to klick "I accept" to install most (proprietary) software.
Basically, all you have to do is install Git on your machine. See http://git-scm.com/downloads to download Git for Windows, OS X, and Linux variants.
 
{{note|You may need to supply a name and an email address when installing.  Don't worry, it's just a prerequisite Git has for use cases you'll never see unless you decide to come to the geek side of life. Needs to be done, just like you have to click {{button|I accept}} to install most (proprietary) software.}}
 
== How do I use the Git repository to update FlightGear stuff? ==
Git has a score of ''very'' confusing options that allow you to do stuff that boggles the mind of even an established geek. To achieve what you, the layman, will want to do, a total of two commands are totally sufficient.


== How do I use the git repository to update Flightgear stuff? ==
Git has a score of '''very''' confusing options that allow you to do stuff that boggles the mind of even an established geek. To achieve what you, the layman, will want to do, a total of two commands are totally sufficient.
=== Initial cloning ===
=== Initial cloning ===
The first step to using the Git data for your own purposes is to grab a copy from the repository. Here's how to do that.  
The first step to using the Git data for your own purposes is to grab a copy from the repository. Here's how to do that.  


This description uses the linux commandline version of the git commands, but in principle you do the same with TrotoiseGit, only the commands are in the context menu there.
{{note|This description uses the Linux command line version of the Git commands, the principles still apply to Git for other operating systems.}}


First, navigate to where you want the checkout to live
==== Step 1 ====
First, navigate to where you want the checkout to live:
<syntaxhighlight lang="bash">
$ cd /home/user/data/git-repos
</syntaxhighlight>


  $ cd /home/user/data/git-repos
==== Step 2 ====
Then, you clone the repository. To do that, you have to know the URL of the repository you want to be cloning. For this example, we'll be using the FlightGear [[base package]] repository '''[[fgdata]]''', but the principle is exactly the same for the [[SimGear]] or FlightGear source. All that changes is the URL to clone.
{{Note|You don't have to create a directory for the checkout. A well-set-up Git repository does that for you with the clone command.}}
{{#tag:syntaxhighlight|
$ {{fgdata clone}}
|  lang = "sh"
}}


Then, you clone the repository. To do that, you have to know the URL of the repository you want to be cloning. Those are found on the [https://gitorious.org/fg Flightgear Gitorious page].For this example, we'll be using the Flightgear Base Data repository '''fgdata''', but the principle is exactly the same for simgear or flightgear source. All that changes is the URL to clone.
After you hit {{key press|Enter}}, it's time to lean back and get a cup of coffee, because that specific repo is ''really big'' – almost 15 GB{{clarify}} of data as of writing this. (There is a better method for cloning huge repositoryies like this, it's described on this page: [[FlightGear and Git#Special for fgdata:|FlightGear and Git]], but it's likely that's exactly the page you fled here from.)
<nowiki>$ git clone git://gitorious.org/fg/fgdata.git</nowiki>
Note also how you don't have to create a directory for the checkout. A well-setup git repository does that for you with the clone command.  


After you hit enter on that line, it's time to lean back and get a cup of coffee, because that specific repo is really quite ''huge'' - almost 15 GB of data as of writing this. (There is a better method for cloning huge repos like this, it's described on this page: [[FlightGear and Git#Special for fgdata:|FlightGear and Git]],but it's likely that's exactly the page you fled here from.)
Now, once that operation completes (without errors hopefully), you're done!  Run these commands …
<syntaxhighlight lang="bash">
$ cd fgdata
$ ls
</syntaxhighlight>
and enjoy.


Now, once that operation completes (without errors hopefully), you're done! Try
{{note|<code>$ ls</code> means ''list all files in the directory''.}}
$ cd fgdata
$ ls
and enjoy.


=== Keeping it current ===
=== Keeping it current ===
Up to this point, we haven't done anything we couldn't have achieved with an archive file. That is, we have, but not in a way you, a layman, are in any position to recognize. Now is the time to take advantage of this fact.
Up to this point, we haven't done anything we couldn't have achieved with an archive file. That is, we have, but not in a way you, a layman, are in any position to recognize. Now is the time to take advantage of this fact.


Let's say you've buggered the guys in the IRC channel until finally somebody has fixed the bug in your favorite airplane just to get rid of you. Now how do you personally get that change? If you had been downloading an archive, you'd have to wait for the archive to be rebuilt, download the whole thing again, and iron it on over the old data. Not so with Git - here's what to do. Navigate to the place where your repository lives, in our example like this:
Let's say you've pestered the guys on the IRC channel until finally somebody has fixed the bug in your favorite airplane just to get rid of you. Now how do you personally get that change? If you had been downloading an archive, you'd have to wait for the archive to be rebuilt, download the whole thing again, and iron it on over the old data. Not so with Git - here's what to do. Navigate to the place where your repository lives, in our example like this:
$ cd /home/user/git-repos/fgdata
<syntaxhighlight lang="bash">
Note that this time, we're cding ''into'' the directory.
$ cd /home/user/git-repos/fgdata
</syntaxhighlight>
 
{{Note|This time, we're <code>cd</code>ing ''into'' the directory.}}
 
Now get all the changes since you cloned the repository like this:
Now get all the changes since you cloned the repository like this:
$ git pull
<syntaxhighlight lang="bash">
That's all. Watch the numbers dance - it'll be much quicker this time than the last time, because only the changes in the files need to be transmitted - and once the command returns, you can jump into your now (hopefully) bug-free airplane and take her for a spin
$ git pull
</syntaxhighlight>
That's all. Watch the numbers dance it'll be much quicker this time than the last time, because only the changes in the files need to be transmitted and once the command returns, you can jump into your now (hopefully) bug-free airplane and take her for a spin


== A word about troubleshooting ==
== A word about troubleshooting ==
This wouldn't be a good article without a word about troubleshooting. The process described above is really rather reliable and will work 99% of the time, but sometimes it '''does''' break down - mostly because you inadvertedly changed a file that somebody else changed in the "official" repository. If Git finds a conflict, e.g. a file having been edited by you AND somebody else since the last pull - it will refuse to just clobber the local changes.  
This wouldn't be a good article without a word about troubleshooting. The process described above is really rather reliable and will work 99% of the time, but sometimes it '''does''' break down - mostly because you inadvertedly changed a file that somebody else changed in the "official" repository. If Git finds a conflict, e.g. a file having been edited by you ''and'' somebody else since the last pull - it will refuse to just clobber the local changes.  
 
Now – if you ''did'' change the file actively, it's time you went over to a ''real'' Git tutorial and found out about merging changes. If you didn't, you can revert the changes to the baseline of the repository, that is, reset the file(s) to how it was when you last pulled the changes:
<syntaxhighlight lang="bash">
$ cd /home/user/git-repos/fgdata
$ git reset
$ git pull
</syntaxhighlight>
 
If it works, all is fine. If Git still complains, e.g., about not being able to "fast-forward" the changes, you'll have to tell it to try a little harder (and with less respect to what it might clobber) to reset your working copy:
<syntaxhighlight lang="bash">
$ git reset --hard
</syntaxhighlight>


Now - if you DID change the file actively, it's time you went over to a ''real'' git tutorial and found out about merging changes. If you didn't, you can revert the changes to the baseline of the repository, that is, reset the file(s) to how it was when you last pulled the changes:
Sometimes, it is simple. This command should undo everything you did in your working copy, that is, get the entire working copy back to the state it was when you last pulled. In 99% of the trouble, this is the end of it, and a  
$ cd /home/user/git-repos/fgdata
<syntaxhighlight lang="bash">
$ git reset
$ git pull
$ git pull
</syntaxhighlight>
If it works, all is fine. If Git still complains, e.g. about not being able to "fast-forward" the changes, you'll have to tell it to try a little harder (and with less respect to what it might clobber) to reset your working copy:
$ git reset --hard
Sometimes, IT is simple. This command should undo everything you did in your working copy, that is, get the entire working copy back to the state it was when you last pulled. In 99% of the trouble, this is the end of it, and a  
$ git pull
will work. If it still doesn't, your local clone has gotten a nasty dent somewhere. In this case, you can either seriously dive into git and fix it, or delete the whole repository folder and clone anew:
will work. If it still doesn't, your local clone has gotten a nasty dent somewhere. In this case, you can either seriously dive into git and fix it, or delete the whole repository folder and clone anew:
$ cd /home/user/git-repos/
<syntaxhighlight lang="bash">
$ rm -rf fgdata
$ cd /home/user/git-repos/
<nowiki>$ git clone git://gitorious.org/fg/fgdata.git</nowiki>
$ rm -rf fgdata
$ git clone git://git.code.sf.net/p/flightgear/fgdata flightgear-fgdata
</syntaxhighlight>


== Where do I take it from here? ==
== Where do I take it from here? ==
To be honest: for most ''laymen'' this is the end of the trail, and you'll live happily ever after.  
For most ''laymen'', this is the end of the trail, and you'll live happily ever after.  


If however your interest has been piqued and you want to know more about Git in particular and VCS in general - and how they can help you tweak and twitch your copy of flightgear - more power to you.  
However, if your interest has been piqued and you want to know more about Git in particular and VCS in general - and how they can help you tweak and twitch your copy of FlightGear – more power to you.  


First, I'd recommend browsing the net for a good git tutorial - a very good one is available from Linus Torvalds, the famous inventor of Linux - and father of Git - but you'll have to find out which one works for '''you'''. Also read [[FlightGear and Git]], the official wiki page on doing Git the Flightgear way.
First, I'd recommend looking for a good [https://www.google.co.uk/#q=git+tutorial Git tutorial] – a very good one is available from Linus Torvalds, the famous inventor of Linux and father of Git but you'll have to find out which one works for '''you'''. Also read [[FlightGear Git]], the official wiki page on doing Git the FlightGear way.


[[Category:Git]]
[[Category:Git]]

Latest revision as of 16:16, 29 February 2016

Git, and its fellow version control systems This is a link to a Wikipedia article are a domain of geeks – who are patently incapable of explaining anything in simple terms most of the time. Because of this, many a layman has fled in terror from what is, when all's said and done, easy to use.

What is Git?

Git is a distributed version control system This is a link to a Wikipedia article (DVCS), meaning that it tracks changes to files – in other words, if you make a change to a file known to Git, or commit the change as the expert would put it, Git stores what parts of the file have changed between the last version and the current version. That makes it possible to do a lot of great things, the most mind-soothing among them being the ability to get the old version back in case it turns out you've broken something.

What does Git do for me?

Another thing Git does is distribute change. That means, additionally to committing things to the Git repository, you can also get the changes others made from the Git repository – thus keeping your local copy of whatever is kept in the repository current. That is the use most laymen will be most interested in. In practical terms, that means you can at any time get all the changes the developers made just by updating your copy from the repository - instead of having to re-download the whole data (or trying to scrape together the changed files manually, a path that leads to insanity without any stop signs or speed limits). With a large repository like the FlightGear base package for example, the difference is a few kilobytes instead of 15 gigabytes.

What do I need to use a Git repository that way?

Basically, all you have to do is install Git on your machine. See http://git-scm.com/downloads to download Git for Windows, OS X, and Linux variants.

Note  You may need to supply a name and an email address when installing. Don't worry, it's just a prerequisite Git has for use cases you'll never see unless you decide to come to the geek side of life. Needs to be done, just like you have to click I accept to install most (proprietary) software.

How do I use the Git repository to update FlightGear stuff?

Git has a score of very confusing options that allow you to do stuff that boggles the mind of even an established geek. To achieve what you, the layman, will want to do, a total of two commands are totally sufficient.

Initial cloning

The first step to using the Git data for your own purposes is to grab a copy from the repository. Here's how to do that.

Note  This description uses the Linux command line version of the Git commands, the principles still apply to Git for other operating systems.

Step 1

First, navigate to where you want the checkout to live:

$ cd /home/user/data/git-repos

Step 2

Then, you clone the repository. To do that, you have to know the URL of the repository you want to be cloning. For this example, we'll be using the FlightGear base package repository fgdata, but the principle is exactly the same for the SimGear or FlightGear source. All that changes is the URL to clone.

Note  You don't have to create a directory for the checkout. A well-set-up Git repository does that for you with the clone command.
$ git clone git://git.code.sf.net/p/flightgear/fgdata/

After you hit Enter, it's time to lean back and get a cup of coffee, because that specific repo is really big – almost 15 GB[clarify] of data as of writing this. (There is a better method for cloning huge repositoryies like this, it's described on this page: FlightGear and Git, but it's likely that's exactly the page you fled here from.)

Now, once that operation completes (without errors hopefully), you're done! Run these commands …

$ cd fgdata
$ ls

… and enjoy.

Note$ ls means list all files in the directory.

Keeping it current

Up to this point, we haven't done anything we couldn't have achieved with an archive file. That is, we have, but not in a way you, a layman, are in any position to recognize. Now is the time to take advantage of this fact.

Let's say you've pestered the guys on the IRC channel until finally somebody has fixed the bug in your favorite airplane just to get rid of you. Now how do you personally get that change? If you had been downloading an archive, you'd have to wait for the archive to be rebuilt, download the whole thing again, and iron it on over the old data. Not so with Git - here's what to do. Navigate to the place where your repository lives, in our example like this:

$ cd /home/user/git-repos/fgdata
Note  This time, we're cding into the directory.

Now get all the changes since you cloned the repository like this:

$ git pull

That's all. Watch the numbers dance – it'll be much quicker this time than the last time, because only the changes in the files need to be transmitted – and once the command returns, you can jump into your now (hopefully) bug-free airplane and take her for a spin

A word about troubleshooting

This wouldn't be a good article without a word about troubleshooting. The process described above is really rather reliable and will work 99% of the time, but sometimes it does break down - mostly because you inadvertedly changed a file that somebody else changed in the "official" repository. If Git finds a conflict, e.g. a file having been edited by you and somebody else since the last pull - it will refuse to just clobber the local changes.

Now – if you did change the file actively, it's time you went over to a real Git tutorial and found out about merging changes. If you didn't, you can revert the changes to the baseline of the repository, that is, reset the file(s) to how it was when you last pulled the changes:

$ cd /home/user/git-repos/fgdata
$ git reset
$ git pull

If it works, all is fine. If Git still complains, e.g., about not being able to "fast-forward" the changes, you'll have to tell it to try a little harder (and with less respect to what it might clobber) to reset your working copy:

$ git reset --hard

Sometimes, it is simple. This command should undo everything you did in your working copy, that is, get the entire working copy back to the state it was when you last pulled. In 99% of the trouble, this is the end of it, and a

$ git pull

will work. If it still doesn't, your local clone has gotten a nasty dent somewhere. In this case, you can either seriously dive into git and fix it, or delete the whole repository folder and clone anew:

$ cd /home/user/git-repos/
$ rm -rf fgdata
$ git clone git://git.code.sf.net/p/flightgear/fgdata flightgear-fgdata

Where do I take it from here?

For most laymen, this is the end of the trail, and you'll live happily ever after.

However, if your interest has been piqued and you want to know more about Git in particular and VCS in general - and how they can help you tweak and twitch your copy of FlightGear – more power to you.

First, I'd recommend looking for a good Git tutorial – a very good one is available from Linus Torvalds, the famous inventor of Linux and father of Git – but you'll have to find out which one works for you. Also read FlightGear Git, the official wiki page on doing Git the FlightGear way.