Hey all,

I've completed my CVS-git mirroring process, and you can now download the
full revision history of cURL via git. To get your own copy of the
repository, run

    git clone http://triplehelix.org/curl.git

And now for a crash course on git.

Making changes:
---------------

Just make changes as you like, and then use

    git commit <files>

to make a commit message, then commit the files. If you want to do a blanket
commit of everything you've edited, use

    git commit -a

git is extraordinarily flexible with commits. It's not worth going into
detail here, but one of the coolest things I can think of is that if you've
made changes to several parts of a file, but only want to commit part of it
(more on why you would want to do that later) you can use

    git add --interactive foo.c

to view the diff, split it into smaller hunks, and 'stage' only certain
hunks that you wish, and leave the rest uncommitted. After using git add, a
git commit (with no arguments) will commit foo.c with only the changes
you've chosen.

If you've really messed it up, you can revert your tree to a pristine state:

    git reset --hard

Updating from CVS
-----------------

The repository is synced to CVS head every 3 hours (in theory, I just added
the cronjob.) To sync, just run

    git pull

This will download new bits from the server, and merge whatever changes you
have made to the main branch to it. If there's a conflict, it'll let you
know and you will have to commit the result to continue. The conflict
resolution is done the same way as in CVS.

'git pull' is actually a shortcut for 'git fetch origin' and 'git merge
origin/master'. More on that below.

Feature branches
----------------

A powerful feature of git is that you can be working on several distinct
changesets at once without being disturbed by changes on the master branch /
CVS head.

Suppose you wish to add FOO protocol support to lib/. You start from your
clean master branch (the one that is created when you run 'git clone'), and
do a

    git checkout -b foo-protocol

You are now on a new branch named 'foo-protocol'. You work on this as above,
making changes and committing as you see fit. When you'd finally like to
catch up to CVS head, you would do this:

    git fetch origin # fetches new bits from server without
                     # applying them to your working tree
    git rebase origin/master # reapplies your changes on foo-protocol
                             # to the latest CVS head

If the rebase succeeds without conflicts, diffs from your branch can be
cleanly applied to CVS HEAD.

Note that 'rebase' is different from 'merge' (as described above) and this
is one of the most difficult to understand but powerful things about git.

- 'rebase' makes it so that changes are applied in this order:
   latest CVS -> your changes
- 'merge' makes it so that changes are applied in this order:
   CVS as of branch creation -> your changes -> latest CVS changes

Using 'merge' may succeed more easily, but it will make it difficult to
submit patches later.

It's recommended to 'rebase' on a regular basis to avoid having to spend 5
hours fixing merge conflicts when you're finally ready to..

Submit patches
--------------

git has powerful support for taking commits you've made to a branch and
creating patches for them. It does this by creating 1 diff from each commit
you make, using the change description as the body of the email message and
providing a 'diffstat' after each one.

Using the foo-protocol example from before, if you want to generate patches
for each commit you've made, use this:

    git format-patch origin/master..foo-protocol

This tells git to select the commits that have happened between CVS HEAD and
foo-protocol (e.g. the changes that YOU made.) This dumps a series of .patch
files in your current directory, prefixed with a serial number that shows
the order in which to apply the patches.

This, by the way, is the reason why it's attractive to be able to only
commit a hunk of a file at once; so that only relevant bits show up in the
resulting patch later.

You can even get git format-patch to send the actual emails through
/usr/sbin/sendmail, but even I haven't figured that out yet :)

That's about all it takes to get started!

Questions?
----------

You can ask me personally, but git also has extensive manpage and online
documentation by both developers and other interested end users. So, give
Google a try before you bug me ;)

-Josh

-------------------------------------------------------------------
List admin: http://cool.haxx.se/list/listinfo/curl-library
Etiquette: http://curl.haxx.se/mail/etiquette.html
Received on 2009-11-09