Git mini howto
This page is a really quick 'n dirty tutorial on how to work with Git. It is strongly biased to the work on Fiji; you should refer to Git's homepage for much more information.
Most of these explanations are meant for the command line users.
A quick note on the nomenclature: fiji.git refers to the "official" repository on . After cloning it, you will have a local repository with a working directory, which will be referred to as "fiji/" in this document (and "cd fiji/" just tells you to make sure you are in that directory).
If you are unsure about the meaning of any Git term, just consult the Git glossary.
You need to clone fiji.git:
$ git clone git://pacific.mpi-cbg.de/fiji.git/
If you want to contribute to Fiji, or if that clone times out (e.g. because you have a restrictive firewall), you might want to try this command instead (although you do not need to reclone if you cloned using the git:// protocol; see "Contributing"):
Both commands will create the directory fiji/ and check out an initial version.
As mentioned in "Cloning", you should clone from ssh://email@example.com/srv/git/fiji.git/. However, you can easily add that as a so-called remote to an existing clone:
$ cd fiji/ $ git add remote contrib ssh://firstname.lastname@example.org/srv/git/fiji.git/
Before doing anything else, you should create a local "contrib" branch:
$ cd fiji/ $ git checkout -b contrib contrib/master
You should name the local branch contrib, because pacific's contrib user -- in exchange for not needing a password -- can only write to the contrib branch. In other words, if you use a different branch, all will work well locally, but when you try to push your changes upstream, it will fail.
Now you only need to make sure that Git knows about you (substitute your name/email here...):
$ git config --global user.name "General Failure" $ git config --global user.email "email@example.com"
Likewise, if your preferred editor is not vi, you might want to do something about that (substitute your pet editor here...):
$ git config --global core.editor xemacs
After initializing the contrib branch, you can work as described in "Making changes" and "Pushing changes upstream".
To get the most recent changes, call
$ cd fiji/ $ git pull
Note: You should always commit your changes before pulling.
$ cd fiji/ $ make
will pick up on all changes, rebuild what needs to be rebuilt, and run Fiji.
In future versions of Fiji, we will no longer rely on "make" being present, although it will always continue to work if available. The new way will be to either execute "fake.jar" directly, or start it using the Fiji launcher: $ cd fiji/ $ ./fiji --fake
You can add/modify plugins, and test by running "make".
Once you are happy with your changes, you should inspect your changes with
$ cd fiji/ $ git status
which will show you which tracked files were modified, and the untracked files (which might need to be added to the Git repository). You can view the diff of your changes with
$ cd fiji/ $ git diff
You should stage the changed/new files for commit, and verify that all files were correctly staged, with:
$ cd fiji/ $ git add <files> $ git status
If all files that need committing were staged correctly, you commit them:
$ cd fiji/ $ git commit
Please make sure that your commit message is in a format like this:
The first line is a short description After an empty line, you can go into details what this commit does, and why. Maybe even how.
Note: a neat trick when you realize that you did not commit after all, is to delete the complete commit message, save and exit. This will abort the commit. The ability to abort a commit comes in pretty handy e.g. when you see an unwanted entry in the list of files to be committed.
For more advanced Git usage, see "Making changes (advanced)".
Pushing changes upstream
All commits are purely local before you decide to publish them. You can do that with
$ cd fiji/ $ git push
Note: if somebody made changes to the branch in the mean-time, you need to pull first:
$ cd fiji/ $ git pull
Note for CVS/Subversion users: With Git, it is highly encouraged to commit first, then pull. Git is really good at branching and merging, and it is better for you to commit a version that you actually tested than to integrate other people's changes before committing. It also helps finding which commit introduced a regression.
Graphical user interfaces
There are a few graphical user interfaces for working with Git. You probably want to look at the commit history with gitk, and you might want to clone/pull/add/commit/push with git gui.
If you are an Eclipse user, you might want to work with the Eclipse plugin.
Making changes (advanced)
Git is aware of three states:
- the tip of the branch (AKA the last committed version, or "HEAD")
- the staging area (also called "the index")
- the working directory
Instead of staging whole files, you can pick just a few changes to be staged:
$ cd fiji/ $ git add -i
This will let you choose single hunks from the unstaged changes and put them into the staging area. It also allows you to revert to the version stored
In git-gui, you can do the same by clicking on the file and then choose Stage this hunk or Unstage this hunk from the context menu you get by right-clicking on the hunk header (the line beginning with @@).
You can inspect what changes are in the staging area with:
$ cd fiji/ $ git diff --cached
When you are comfortable with the staged changes, just commit with
$ cd fiji/ $ git commit
Even more advanced Git usage involved topic branches.