After the 1.4.13 release, the Nagios Plugins development team moved to Git for its code repositories. This document is a quick introduction to Git.
Subversion is still updated automatically from Git, though the distributed nature of Git can make come strange commit patterns.
There is one huge difference between Git and SVN: Git is a distributed SCM (Source Code Management) while SVN is a centralized one. This doesn't mean we can't have a central shared Git repository (and we indeed have one), this means distributed development can occur around that central repository.
Another visible difference is that Git have more stages between the working directory and the repository. When you want to add files or changes, you use git add. This adds the changes to the repository index, which can be seen as a staging area. When you commit with git commit, only the changes in the index are considered. After committing, the changes are still local. To share it with others, you have to push it to a remote repository, or gave someone pull from your publicly accessible repository (in most case you will still have to push changes there, unless if you were running a git daemon straight off your working repository).
Finally you can't miss the fact that there is no more revision numbers, and the distributed nature of Git is the reason for that: there is absolutely no way a single number could be tracked in a distributed way. Instead Git uses SHA1 hashes to identify commits (as well as other objects in the repository). Each branch and tag refer to an object name (SHA1 hash), and each commits have one or more parents (commit objects). Although SHA1 hashes are 40-digits long, with Git you only have to type a handful of digits to reference one.
There are three projects:
You can see all the projects from the following web interface (Gitweb):
http://nagiosplug.git.sourceforge.net/
The following notes are for the nagiosplug project, but can be substituted for any of the others.
To work on a project you first have to clone it. This creates your own local repository and until you want to distribute your change or merge changes from someone else everything that follows can happen offline.
If you have push access, run the command:
git clone ssh://<user>@nagiosplug.git.sourceforge.net/gitroot/nagiosplug/nagiosplug
where <user> is your user name at SourceForge.
If you just want a local copy or wish to clone it to your workstation, you can run this command instead:
git clone git://nagiosplug.git.sourceforge.net/gitroot/nagiosplug/nagiosplug
This will create a directory called nagiosplugins in your current directory with all the "master" code and history (this is roughly equivalent to CVS/SVN HEAD). Change directory to nagiosplug.
You can edit the files in the working area. To check the status, use:
git status
This will show a list of changes in the working directory. Newly make changes appear in RED, while changes added to the index are shown in green. You can use git diff to see changes between the current working directory and the index (untracked files will not be shown)
Use git add to specify which new files/changes you want to commit; this will add the changes to the index. You can select only partial diffs with git add -p too. If you want to commit everything you can use git commit -a directly.
You can see the changes you are about to commit (difference between HEAD and the index) with git diff --cached, and then commit them with:
git commit
Add a comment (you have read the developers guidelines, right? :) ). This commit will be local (affecting only your own repository) so you will have to either push your changes, or have someone to pull them from you (in the latter case you will most likely still push to a publicly accessible clone of your local repository).
If the change is from a contributor, set the author at commit time:
git commit --author="Ton Voon <ton.voon@opsera.com>"
If you realize that you forgot something in your commit and haven't pushed it yet to a remote repository, you can amend your last commit with git commit --amend. You can also amend after a push and force the next update, however this will cause non-linear updates and should be done only if the developers using your repository are aware of it.
You can revert local modifications with the following steps.
First, if you have already staged the changes you will have to unstage them. As indicated in the "git status" message you can do so with the following command:
git reset HEAD <file>
Then you can revert unstaged changes with:
git checkout <file>
If you have already committed changes locally and need to undo your commit(s), you can use git reset. First find the commit names with git log and then do either one of these:
To keep local modifications (you can commit them again, stash them, etc.)
git reset --soft <commit>
Note that for the purpose of "re-doing" the last commit, git commit --amend will be much easier than a reset/commit with the same end result.
To discard local modifications (if you lose important changes with this command you may be able to recover them with git reflog and git checkout <commit>):
git reset --hard <file>
Do not reset changes that have already been pushed to remote repositories as this will cause non-linear updates. If you do so, developers using those repositories should be aware of it.
When you work on your local repository you'll need to keep it up to date with the development tree. This is very similar to svn update with the difference that it can't be done if the working tree has any unmerged changes. If you do, either commit them or put them aside (Tip: git stash). If you cloned from the main Git repository, this command will do a fetch then merge any new changes:
git pull
You can also merge changes from any other fork of the repository. This usually happens if someone ask you to pull from his own repo for some fix or enhancements. Together with --no-commit you will have a chance to review the changes and make any relevant correction before the merge. Ex:
git pull --no-commit git://host.xz/path/to/repo.git/ master
Once you're done with your commits and after pulling from the main repository, you can push you change back to it. If you cloned using the push url this command will push the master branch:
git push
It you're trying to push something that would generate merge conflicts, the push will be rejected. You will have yo do a pull first, fix the any conflicts locally and then push again.
If your commits are local (you haven't pulled them from someone else or published them somewhere) you can rebase to avoid a merge:
git pull --rebase
Like a merge, this may generate conflicts and let you fix them, but instead of creating a merge commit on top of the others, it will undo your commits, fast-forward and apply your commits again. This is cleaner but doesn't play well when it rewrites already published history.
If you are doing some development that you want to experiment with, you can create a new branch with:
git branch newbranchname
Switch to this branch with:
git checkout newbranchname
Show your current branch with:
git branch
This will list all branches with a * next to the current branch.
If you want to push a local branch up to a remote repository, run:
git push origin newbranchname:experimental/branchname
This tags the branch at the remote site with experimental/branchname.
This is a very quick introduction to Git. There are a lot more useful commands for manipulating changes and working with others. Be sure to have a look at the references below to better understand how git works. All standard commands are very well documented as well (git help [-a] for a list of commands, git help <cmd> or git <cmd> --help shows the man page).
I highly recommend reading Git for Computer Scientists (http://eagain.net/articles/git-for-computer-scientists/) to understand how rebase works.