How to access Thousand Parsec Source Code

Quick Summary

To check out a copy of the code make sure you have Cogito installed, then use the following command:

cg-clone git://git.thousandparsec.net/git/<project>.git

Projects can be found by browsing the gitweb at http://git.thousandparsec.net/.

To update from upstream use cg-update.

Developers can access the git tree using:

cg-clone git+ssh://user@git.thousandparsec.net/var/lib/git/project.git

Resources

There are a fair number of resources available for git. The git website has a many available.

For people with some understanding of revision control systems (such as CVS) take a look at Everyday Git in Twenty Commands or So. This covers most the things that you will use most of the time. It focuses on Git rather then cogito.

For cogito the introduction is excellent, and is probably shipped with your distrubution (for debian uses try: file:///usr/share/doc/cogito/introduction.html). Otherwise it is online at: http://www.kernel.org/pub/software/scm/cogito/docs/introduction.html.

Other good resources include the CVS Crash Course, SVN Crash Course, A tutorial introduction to git, The Kernel Hackers' Guide to git, and even Git And Wine (from the wine project).

One short warning, make sure you are looking at documentation for the correct version of git. At the time of writing git is at version 1.5.1. A lot of documentation around focuses on git 1.4 and earlier, and there are some notable interface improvements between 1.4 and 1.5.

Using Cogito

Getting a local copy: cg-clone <url>. The URL can be fond above. You have a local branch called 'master' and the upstream URL will be called 'origin'.

To commit changes use cg-commit. If you only want to commit a few files use cg-commit file1 file2.... Note you can also edit which files are commited by editing the commit message.

cg-status shows a list of changed files (and branches) and cg-diff shows you your changes. You can check individual files by passing them on the command line. Specific versions can be checked using either their full name (40 byte SHA1 string), a shortened prefix (d7f55783836f or even d7), a tag name, or relative to any of the above using ^ (parent), ~n (nth ancestor) or a number of other ways. man git-rev-parse for the full list of specifying revisions (in short, almost any way you can think of).

You can register new remote branches (eg from another developer) by using cg-branch-add localname remoteurl. You can update your local cache of the remote branch using cg-fetch. This allows you to diff between the branch using cg-diff -r remotename. Similarly you can use ^ and similar notations to get history of the changes.

You can merge in changes using cg-merge branchname. If you want to merge a single patch, look at git cherry-pick (not covered in any more detail here.

If you want to fetch and merge a set of changes together (for instance from upstream) use cg-update branchname. The default branch is origin if none is supplied.

Creating local branches (or heads) is really easy too. To create a new head you just call cg-switch -c branchname. cg-status shows you the current branch with a '>' (R indicates a remote branch). To switch between branches use cg-switch branchname. If you want to look at a remote branch you have to use cg-seek branchname. This allows you to explore the history and the like, but not make changes. You can also use cg-seek to check out old versions of local branches as well.

Using Git

Future work...

Sending Patches

If you don't have developer access to the git archives (most people won't until they have a track record of useful and good patches), there are two ways to send patches to the developers to be applied to the main tree, email and by remote pulls. Email is the easiest to set up, and best for infrequent (and new commiters.

By Email

Git is quite happy to generate emails to send to the thousand parsec mailing lists for you. It can either save them into an imap mail box, or a text file to be editied by your mail client.

To send via IMAP, you need to set up git-imap-send first. Once that is done (which you only need to do once), you can generate a patch using:

git format-patch --stdout --keep-subject --attach origin | git imap-send

Otherwise, you can generate the patch as a plain text file using:

git format-patch --keep-subject origin

Send the patch to the tp-devel list. Reviews and comments will be posted there, while tp-cvs will have commit logs of committed patches.

Otherwise if you have your branch in a place a developer can access, he can do a cg-pull to bring you changes in.

.