Hello,
As we will very soon have quite a few new students (thanks Google!) who
will need to be able to commit code to our repositories, I thought I
would write a simple guide to using Darcs (specifically with Thousand
Parsec repositories).
________________________________________________________________________
I am in no way an advanced Darcs user, so please take everything in this
manual with a grain of salt.
The first thing you need to understand about Darcs is that it is a
distributed system rather then a centralised system. The key to the
difference is that there is separation between "recording changes" and
"pushing changes". In CVS the two are intimately connected, you record
changes *by* pushing to a remove repository. Subversion being a "better
CVS" works in a very similar way.
So enough about philosophy stuff, how do we actually use it? The first
thing you'll want to do is get the code. With Subversion or CVS you use
the "check out" command. With darcs you use the "get" command.
> darcs get --partial http://darcs.thousandparsec.net/repos/<repository>
For example, here is me getting the scratchpad repository,
[EMAIL PROTECTED]:~/oss/tp/temp$ darcs get --partial
http://darcs.thousandparsec.net/repos/scratchpad
Copying patch 20 of 20... done!
Applying patch 20 of 20... done.
Finished getting.
[EMAIL PROTECTED]:~/oss/tp/temp$
In CVS or Subversion you where able to get all repositories using
something like
> cvs co -d:pserver:[EMAIL PROTECTED] co .
You can not do this with darcs. You have to checkout each repository
separately.
________________________________________________________________________
There is also a "magic script" which should help you setup a
development environment quickly. This script is very new and
still needs a lot of work.
Type the following commands can be used to use the magic script.
> wget
http://darcs.thousandparsec.net/repos/scratchpad/magicsetup.sh
> sh magicsetup.sh
________________________________________________________________________
Once you have checked out the repository you can then go about modifying
the code. How you do this is up to you, I prefer using Vim.
Once you have made changes, you can then "record" them. Unlike CVS or
Subversion, recording changes does not cause them to become public. This
means that you can record many changes before the code is in a state
which you are willing to "push" to the public.
To record a change you use the following command
> darcs record
To record only changes in a specific file or directory use
> darcs record <file or directory>
Darcs will then ask you about which changes it should put in this patch.
It's an interactive process that should be pretty simple to follow. If
you need help, type ? and it enter.
________________________________________________________________________
The "patch name" should be a 1 line summary of what has changed.
Things like "Add new starmap view." or "Add support for xyz".
If you want to give more details or specifics, please do so in
the "long summary" section. Extra detail is always recommended.
________________________________________________________________________
It is recommended that you record often. This allows you people
to see how you developed the code and what fixes you made.
It also makes it much easier for the developers to "cherry pick"
the good changes while you are still learning.
Lots of little patches are definitely very much preferred to a
few big patches.
________________________________________________________________________
Sometimes before you record, you want to find out what changes have
occurred. Darcs has the "whatsnew" command to find out what has
occurred. The following command will tell you what has changed,
> darcs whatsnew
The output will kind of look like the same as a unified diff output.
Here is some sample output,
{
hunk ./requirements.py 52
+ try:
+ import wxversion
+ except ImportError:
+ pass
+
}
This output often has way to much information, you just want to figure
out which files have changed, and how much they have changed. You use
the following arguments to whatsnew to get a sort "summary" output.
> darcs whatsnew -s
The output format will look something like this
[EMAIL PROTECTED]:~/oss/tp/tpclient-pywx$ darcs whatsnew -s
M ./doc/manual/tpclient-pywx-manual.sla -76 +36
M ./requirements.py +5
M ./windows/winConnect.py -1 +1
Like CVS and Subversion you need to tell Darcs about any new files that
you create. You can find out which files Darcs doesn't know about with
the following command,
> darcs whatsnew -sl
To tell Darcs about a new file you use the "add" command.
> darcs add <file to me added>
You can then record the initial state of the file.
Once you have the code in a state in which you want other people to look
at, you have two options to push it. If you do not have commit access
you will need to use the "send" command. Send should be use to create a
file which contains the changes you have recorded.
> darcs send -o <file>
Once you have the file, just email it off to the correct person or
attach it to a bug report. If somebody applies the changes you send in,
you will get the credit!
If you do have commit access you can use the push command. The first
time you push, you'll have to tell darcs where to push too.
> darcs push
<username>@darcs.thousandparsec.net:/var/lib/darcs/repos/<repository>
Once you have pushed to a repository, it becomes the default one. You
can then just run
> darcs push
To push any changes.
________________________________________________________________________
To push to a Thousand Parsec server you will need to use ssh
keys.
You can generate a ssh-key using the "ssh-keygen". If you choose
to have a pass phrase protecting your key (which is highly
recommended) you will need to use ssh-agent and load the keys
before pushing.
The good news if you run gnome on a decent Linux operating
system, you already have ssh-agent running. Before pushing you
will need to run
> ssh-add <key file>
The command will ask you for the pass phrase protecting your
key. Once the key is loaded, you should be able to ssh to the
machine without having to reenter the pass phrase or enter a
password.
________________________________________________________________________
However, source control is about working with other people. You will
often want to pull code from the public repository. To do this is really
simple, you just use the "pull" command.
> darcs pull
You can even selectively pull patches, Darcs will work out the
dependencies for you and make sure you don't get into a mess.
A useful feature which doesn't exist in CVS is the "revert" command.
This is good when you make a change and then realise "doh!" that change
was horrible wrong. The revert command will then help you get back to
the original state. I use revert all the time, particular because I'm a
scatter brain and get halfway through things.
________________________________________________________________________
Here are also some useful thinks which are probably a lot better then
this guide,
* Darcs Manual - http://www.darcs.net/manual/
* Darcs Instructions for PSI -
http://psi-im.org/wiki/Darcs_Instructions
* Darcs Wiki - http://darcs.net/DarcsWiki
* Darcs FAQ - http://darcs.net/DarcsWiki/FrequentlyAskedQuestions
Hope this all helps. I should probably work on this a bit more and put
it up on a web page somewhere but this is all of it for now.
Tim Ansell
_______________________________________________
tp-devel mailing list
[email protected]
http://www.thousandparsec.net/tp/mailman.php/listinfo/tp-devel
