Howto:Start using git
Git is a version control system, used to store all files required to build FlightGear.
A handful of useful commands
To get started using git, you really just need to know a handful of commands in the beginning:
- git init name
- Create a completely new empty repository (will not be needed for FG, just for experiments/testing)
- git clone URL
- Create a copy of a git repository locally (that's what you have done already to get the fgdata repository)
- git status
- View the status of the current repository
- git diff
- View differences
- git pull
- Pull (=download and merge!) latest updates from the repository that was used for cloning (for updating the local master branch using the origin)
- git pull --rebase
- Pull and rebase your own changes on top of the pulled data
- git branch
- Show active branch and display list of other local branches
- git branch branchname
- Create a new branch using branchname (branch = working copy)
- git checkout branchname
- Checkout a certain branch (in essence switch to that branch and make it active)
- git add filename
- Specify which new or modified files shall be added to the next commit (wildcards supported)
- git commit -m "Message"
- Commit all files that you previously added using "git add" and add a short message about your work.
A common commit message format is the 50/72 format, a short summary (less than 50 characters) followed by an empty line and a longer summary with slightly longer lines (less than 72 characters each).
Because creating a new branch and checking it directly afterwards out, is such a common operation there is a short cut available: git checkout -b my-branch
Git usage basics
To update the base package use git pull (issued in $FG_ROOT) on the UNMODIFIED master branch (which is the default).
This will then keep the "master" branch updated. To get a list of local branches use git branch. This will also tell you what branch you are currently on.
However, assuming that you modify your base package for your own work, it will indeed be better to do this in another branch (i.e. a topic branch), otherwise your own modifications may conflict with the checkout from the server, once you do a git pull so that you will have to manually merge everything. Make sure to use use git status and/or git diff on the master branch to see if you have already done any modifications that may complicate the update.
The easiest thing to do would indeed be to locally create a branch of $FG_ROOT, where you save all your work, this can be done using git branch branchname, where branchname could for example be "local-weather". So just enter the base package folder and type git branch local-weather, you should really be doing this only with a clean/unmodified master branch.
Once you issue then another git branch, you'll see your newly created "local-weather" branch in the list of local branches.
To switch to this new branch use git checkout local-weather, that may take a second or two given the sheer size of the base package. Then you have a 1:1 copy of the last version of the master branch for doing your own local work. This is why I suggested not to create a branch from a modified master, because it will be more complicated to update it automatically.
Basically: always leave the master branch alone, and only do work on topic branches, so that you can easily update the master branch.
For adding modifications/files to your own topic branches, simply use "git add filename". And when you are finished with a change, use "git commit" to commit your modification to your topic branch.
And whenever you want to update your base package, you change back to the master branch using "git checkout master". Keep in mind that the branch you are on is also having an effect on what fgfs sees, because git will literally checkout a copy from the branch, so don't be surprised when your updated work is suddenly not shown in FG, because then you may find that you are still on the default master branch.
Instead of directly doing all this with the base package, I would spend 30 minutes playing with the basics, just by creating a new folder, where you play with modifying a simple text file (think Nasal script) and create branches of it. That is really the easiest way to understand the underlying concepts, without frustrating experiences.
mkdir gitlearn cd gitlearn git init git branch echo "Hello World" > hello.txt git add hello.txt git commit -m "My first commit" git branch new-version git checkout new-version echo "Hello World Ver. 2" > hello.txt git add hello.txt git commit -m "Second version of my program" git checkout master git diff new-version
As you'll see, it's fairly easy to do, but it is important not to start with a real project right from the beginning, but instead become familiar with everything first.
Once you understand these basics, I would however suggest to play with modifying and maintaining your scripts in git, it really is fairly and gives you hands on experience, just make sure that it is a copy of the script that you play with first.
Simple step by step tutorials
There are obviously many more advanced topics, but this bunch of 3-5 commands should get you going pretty quickly, things become slightly more interesting, once you want to directly commit to a remote repository or once you need to track and merge multiple branches.
Online screencasts about doing specific tasks
A bunch of fairly simple beginner tutorials
In order of complexity.