Difference between revisions of "Git mini howto"

(Add a mini HOWTO for working with Git)
(No difference)

Revision as of 14:08, 13 June 2008

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.

Nomenclature

A quick note on the nomenclature: fiji.git refers to the "official" repository on [1]. 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.

Cloning

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"):

$ git clone ssh://contrib@pacific.mpi-cbg.de/srv/git/fiji.git/

Both commands will create the directory fiji/ and check out an initial version.

Contributing

As mentioned in "Cloning", you should clone from ssh://contrib@pacific.mpi-cbg.de/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://contrib@pacific.mpi-cbg.de/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 "general@failure.harddrive.org"

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".

Updating

To get the most recent changes, call

$ cd fiji/
$ git pull

Note: You should always commit your changes before pulling.

Running Fiji

A simple

$ 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

Making changes

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.

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.