Graeme's Wiki : git howto

Graeme's Wiki

Navbar

H o m e
I n d e x
F r e e P a s c a l
t i O P F
f p G U I T o o l k i t

Options

E d i t P a g e

git howto

Git is a fast, efficient, fully distributed SCM, used in many projects like the Linux kernel, Xorg, Freedesktop, and us. :-)

Features

Distributed: this feature enables offline operation, that means, you can commit, branch, and merge without connecting to the server.
Branching and merging: unlike svn, it's fast and comfortable.
Fast: most operations are very fast, more than svn operations on a local repository.
Full history: it keeps the whole development history, still repositories are only a bit bigger than normal svn checkouts. That means all operation except those explicitly made for synchronization are local.

Setting Up Git

First of all, Git must know your name and email address to properly credit your commits. If you don't want to expose your e-mail, just set it to your username/nick.

  $ git config --global user.name "Yourname"

  $ git config --global user.email "your@email"

If you want to override something for a specific project only, just execute the comand without --global.

Getting Started

First you must get a copy of our repo:

  git clone git://github.com/graemeg/fpGUI.git fpgui

  cd fpgui

Make your own branch to work comfortably, the fastest way is:
```
  git checkout -b mybranch
```

This is recommended to keep the consistency and ease interoperability. Branches are lightweight, you should make branches for every significant change. Keep yourself organized and save a lot of effort to get your code into the main repo ;).

A good practice with git is to do small commits, instead of big ones involving many changes, that way we avoid conflicts when merging individual sets of commits.

After you have some changes, you need to mark the files for commit, and do the actual commit:

  git add file1.c file2.c file3.c

  git commit -m 'Message'

This saves a revision in the development history of your repo.

The files can be specified at commit time too:

  git commit -m 'Message' file1.c file2.c file3.c

Or commit all the changes using the -a flag:

  git commit -a -m 'Message'

If you don't specify a message with -m it will open an editor, just like with most other vcs.

Getting your changes merged upstream

Clone our repo on GitHub (or on SourceForge.net), push your changes to your private repo and do a merge request.

Or optionally you could publish your changes on your own repo, and ask a request on the newsgroups. :-)

We will point out any issue in your patch, and once there's none left we will merge it :).

Another option is to send the changesets as a patch to our mailing list or directly to some developer if you feel more comfortable that way. You will want to take a look at the git format-patch command ;-).

Please keep in mind that:

Not all patches will be accepted, ask first. However we may host and even distribute it along fpGUI, just ask :).
If you keep in touch with us and ask for review problems will be pointed out earlier and will be easier to fix.
You should never ever edit published history. If you have to, please name the branch accordingly, something like mybranch-volatile will do the trick.

Tips

If you're playing too much with something, you may wish to edit the history, specially before asking us to merge it.

If you do, please do it on a "private" branch, i.e. an unpublished or auxiliary branch (you can name it in the aforementioned way).
Create topic branches to work on, multiple unrelated changes shouldn't live together.

If the changes are related in some way, and big enough, but not mutually depended, you should create a topic branch too.

Tools

There are two nice graphical tools to work with git: git-gui and gitk. Try them. ;-)

Applying 3rd-party patches

When you receive a patch (or series of patches) by mail, you should export it as a mbox and apply with git-am.

Example:

  git am mbox-file

If you carefully reviewed and tested the patch, then you can sign-off it with the -s parameter. Authors shouldn't sing-off their own patches.

Patches targeting a stable branch should be reviewed by at least two developers before inclusion.

Merging via command line

You can perform a merge (3rdparty contribution) on the command line as follows:

Step 1: From your project repository, check out a new branch and test the changes.

git checkout -b JonnyTech-patch-1 maint
git pull git://github.com/JonnyTech/fpGUI.git patch-1

Step 2: Merge the changes and update the upsteam repository.

git checkout maint
git merge --no-ff JonnyTech-patch-1
git push origin maint

Saving space

  git repack -a

  git gc --aggressive

NOTE: It's not recommended to repack a repo served through a dumb protocol (http, ftp, etc.), since that would cause the clients to fetch the whole pack even if they need only a few objects on it.