Howto:Start using git

From FlightGear wiki
Jump to navigation Jump to search
Git

Git is a version control system, used to store all files required to build FlightGear.

I copied my original forum response This is a link to the FlightGear forum. here. This is specifically meant for people new to source code management systems, who would just like to start using git without learning all the nitty gritty details.

If you are looking for a newbie-friendly GUI frontend to git, you may want to take a look at SmartGit (multi-platform). See TortoiseGit for a Windows specific GUI.

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.

External links

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.

Retrieved from "https://wiki.flightgear.org/w/index.php?title=Howto:Start_using_git&oldid=136761"