Howto:Start using git

I copied my original forum response 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.

To get started using git, you really just need to know a handful of commands in the beginning:

git init NAME - to create a completely new empty repository (will not be needed for FG, just for experiments/testing)

git clone URL - to create a copy of a git repository locally (that's what you have done already to get the fgdata repository)

git status - to view the status of the current repository

git diff - to view differences

git pull - to pull (=download AND merge!) latest updates from the repository that was used for cloning (for updating the local master branch using the origin)

git branch - to show active branch and display list of other local branches

git branch BRANCHNAME - to create a new branch using BRANCHNAME (branch=working copy)

git checkout BRANCHNAME - to checkout a certain branch (i.e. switch to that branch, make it active)

git add FILENAME - to specify which new or modified files shall be added to the next commit (wildcards supported)

git commit -M "COMMENT" - commit all files that you previously added using "git add" and add a short comment about your work

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

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.

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.

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.