• What is darcs?
• How do I install Darcs?
• Read-only access
  • Getting a fresh copy for read-only access
  • Updating your copy
  • Recording local changes
  • Submitting patches
• Read-write access
  • Setting up your $PATH on the Chalmers system
  • Setting up ssh alias and ControlMaster
  • Setting up an ssh ControlMaster connection
    • Automating the ControlMaster connection
  • Getting a fresh copy
  • Getting other people's changes?
  • Commit your changes
  • Apply a patch from someone else
• Troubleshooting
  • I get the error "darcs not found" when pushing
  • I get the error "(sftp) failed to fetch files."
  • I get the error "Not a repository: gfreposerver:..."
  • I'm using Cygwin and I get "mm_receive_fd: no fd"
  • How do I avoid typing in my password so many times?
    • Using ssh ControlMaster
    • Using ssh-agent
• Technical Information
• Further information about Darcs

GF has now been moved to a Darcs repository. No changes should be committed to the CVS repository from now on.

What is darcs?

Darcs is a decentralized revision control system. These are some of the reasons for switching GF from CVS to Darcs:

• you can keep local revision control in your checked-out copy, since each checked-out copy is a repository in itself. For example, this allows the WebALT project to keep a local GF repository for working on the resource grammars, and submit patches to the main repo when that is convenient. It also allows individual developers to keep revision control over their own modifications before they are ready to submit them, or if they are temporarily without net access.

• we can provide read-only access over HTTP using the existing CS web server.

• it is possible and easy to rename and remove both files and directories.

For more information about Darcs, see http://darcs.net/.

How do I install Darcs?

There are precompiled packages for many platforms available at http://darcs.net/DarcsWiki/CategoryBinaries.

There is also source code if you want to compile it yourself. Darcs is written in Haskell and you need GHC to compile it.

Read-only access

Getting a fresh copy for read-only access

Anyone can get the latest development version of GF by running (all on one line):

  $ darcs get --partial --set-scripts-executable http://www.cs.chalmers.se/Cs/Research/Language-technology/darcs/GF/

This will create a directory called GF in the current directory. See GF/src/INSTALL for instructions on compiling. The main difference to compiling a GF release from sources is that you need to run autoconf before configure.

Updating your copy

To get all new patches from the main repo:

  $ darcs pull -a

This can be done anywhere in your local repository, i.e. in the GF directory, or any of its subdirectories.

Without -a, you can choose which patches you want to get.

Recording local changes

Since every copy is a repository, you can have local version control of your changes. To record some changes, use:

  $ darcs record

This creates a patch against the previous version and stores it in your local repository.

Submitting patches

If you are using read-only access, send your patches by email to someone with write-access. First record your changes in your local repository, as described above. You can send any number of recorded patches as one patch bundle. You create the patch bundle with:

  $ darcs send -o mypatch.patch
  $ gzip mypatch.patch

(where mypatch is hopefully replaced by a slightly more descriptive name). Since some e-mail setups change text attachments (most likely by changing the newline characters) you need to send the patch in some compressed format, such as GZIP, BZIP2 or ZIP.

Send it as an e-mail attachment. If you have sendmail or something equivalent installed, it is possible to send the patch directly from darcs. If so, replace -o mypatch.patch with --to=EMAIL where EMAIL is the address to send it to.

Read-write access

If you have an account on the Chalmers system and want read-write access, you can access the repository using ssh. You need to be a member of the langtech group to push changes to the repository.

Note: we seem to have some problems getting read-write access working smoothly on Windows. If you figure out how to do this, let us know. If not, you can still use read-only access, record patches in your local repository, and send them by e-mail once in a while.

Setting up your $PATH on the Chalmers system

The darcs program has to be on your $PATH on the Chalmers system to make it possible for you to push changes to the main repository. To fix this, log in to your Chalmers account and run:

  mkdir -p $HOME/.vcs4
  echo unsup >> $HOME/.vcs4/pathsetup

Note that the path setup works differently on different Chalmers machines. The command above will setup you path on the newer machines correctly.

Setting up ssh alias and ControlMaster

In order to avoid typing in you password multiple times for each action on the remote repository, you can use ssh's ControlMaster functionality. This allows several ssh instances to use the connection established by one existing instance.

NOTE: You need OpenSSH version 4 or newer for this to work. You can check your OpenSSH version with ssh -V. If you have an older version of OpenSSH, you need to remove the ControlPath line below, and you can skip the "Setting up an ssh ControlMaster connection" step. You will be typing in your password a lot...

Add this to ~/.ssh/config (create the file if it does not exist, replace bringert with your own username on the Chalmers system):

  Host gfreposerver
  HostName momo.medic.chalmers.se
  User bringert
  ControlPath /tmp/ssh-gfreposerver

This sets up an alias gfreposerver for the server we use for the Darcs repository. Note that you really need to use momo.medic.chalmers.se (or some other server with the new Linux system) since we need to have a server with Darcs 1.0.4. If you use some server with an earlier Darcs version you can mess up the repository.

More information about the ControlMaster feature is available in man ssh_config.

Setting up an ssh ControlMaster connection

Before connecting to the remote server, you need to set up a master ssh connection to it. As long as this connection is up, you don't need to enter your password when connecting to the GF repository server.

Start the master connection:

  $ ssh -M gfreposerver

This looks just like a normal ssh login, and you get a shell on the server. Put this connection in the background, or keep it open in a window somewhere.

NOTE: You need to have a ControlMaster connection running whenever you want to access the repo using ssh. You may want to create a script or alias for starting the connection.

Automating the ControlMaster connection

You can use a darcs wrapper which sets up a ControlMaster connection if there isn't one already. Put the script darcs-cm somewhere on your path and use it instead of darcs to work with the remote repository.

Getting a fresh copy

Get your copy with (all on one line):

  $ darcs get --partial --set-scripts-executable gfreposerver:/users/cs/www/Research/Language-technology/darcs/GF/

The option --partial means that you do not download all of the history for the repository. This saves space, bandwidth and CPU time, and most people don't need the full history of all changes in the past.

Getting other people's changes?

Get all new patches from the main repo:

  $ darcs pull -a

Without -a, you can choose which patches you want to get.

Commit your changes

There are two steps to commiting a change to the main repo. First you have to record the changes that you want to commit:

  $ darcs record

This creates a patch against the previous version and stores it in your local repository. You can record any number of changesets before pushing them to the main repo. In fact, you don't have to push them at all if you want to keep the changes only in your local repo.

If you think there are too many questions about what to record, you can use the -a flag to record. Or answer a to the first question. Both of these record all the changes you have in your local repository.

Then you can push the patch(es) to the main repo. If you are using ssh-access, all you need to do is:

  $ darcs push

If you use the -a flag to push, all local patches which are not in the main repo are pushed.

Apply a patch from someone else

Use:

  $ darcs apply < mypatch.patch

This applies the patch to your local repository. To commit it to the main repo, use darcs push.

Troubleshooting

I get the error "darcs not found" when pushing

If you get darcs not found when you try to push your changes, you don't have darcs on your $PATH on the Chalmers system. See the section above on setting up your $PATH on the Chalmers system.

I get the error "(sftp) failed to fetch files."

There seems to be a problem with how darcs 1.0.4 calls sftp, which means that normal password authentication does not work. Either use Darcs 1.0.3 on your client, and be prepared to enter your password many times, or use the ssh ControlMaster feature as described above.

I get the error "Not a repository: gfreposerver:..."

You get this error when you have set up ControlMaster, but don't have a master connection running. Start a master connection:

  $ ssh -M gfreposerver

or use the darcs-cm script shown above.

I'm using Cygwin and I get "mm_receive_fd: no fd"

It seems like ssh connection multiplexing doesn't work under Cygwin: http://www.mail-archive.com/cygwin@cygwin.com/msg61323.html.

The workaround is to use password authentication. Just remove the ControlPath line in .ssh/config, and don't setup a ControlMaster connection (and don't use darcs-cm).

You should then be able to checkout using just:

  $ darcs get --partial --set-scripts-executable gfreposerver:/users/cs/www/Research/Language-technology/darcs/GF/

The problem is that when you pull and push, you have to enter your password quite a few times.

How do I avoid typing in my password so many times?

Using ssh ControlMaster

See above.

Using ssh-agent

NOTE: the method below will not work with momo.medic.chalmers.se. MEDIC has decided to disable public key authentication on all new machines. This section is included just for reference in case they decide to enable it again.

With the ssh access method, Darcs needs to log in with ssh. For some reason it needs to do this several times for each operation. You can avoid this by setting up public-key authentication for ssh.

Here is a guide to setting this up: http://cfm.gs.washington.edu/security/ssh/client-pkauth/

Short summary (should on most modern Linux distros, maybe other platforms too):

Generate a key pair:

  $ mkdir -p ~/.ssh
  $ chmod 700 ~/.ssh
  $ ssh-keygen -q -f ~/.ssh/id_rsa -t rsa
  Enter passphrase (empty for no passphrase): ...
  Enter same passphrase again: ...

Upload the public key to your Chalmers account (replace bringert with your username):

  $ ssh-copy-id -i ~/.ssh/id_rsa.pub bringert@remote.cs.chalmers.se

Add the key to ssh-agent (ssh-agent then remembers your key for a while, so that you don't have to type in the passphrase again):

  $ ssh-add
  Enter passphrase for /home/bjorn/.ssh/id_rsa: ...

This is the part that is most likely to fail. If ssh-add says that it couldn't find ssh-agent, you need to follow the instructions linked to above to start ssh-agent.

Try to use it to log in (with your own username again):

  $ ssh bringert@remote.cs.chalmers.se
  ...
  zsh:bringert:[~]>

Technical Information

This section contains information about how the repository is set up. It might be useful for troubleshooting the repository setup or creating a similiar setup for another repository.

The main repository is in /users/cs/www/Research/Language-technology/darcs/GF, which is visible to the web server. The repository and all files and directories in it group writable, owned by the group langtech, and all directories have the setgid bit set:

  drwxrwsr-x  10 bringert langtech 512 Nov 17 19:00 /users/cs/www/Research/Language-technology/darcs/GF

The repo has this in _darcs/prefs/defaults:

  apply posthook find . -user "$USER" -a ! -perm +g+w -exec chmod g+w '{}' ';'
  apply run-posthook

The server which we push to has darcs 1.0.4, which is needed for posthook support.

Further information about Darcs

For more info about what you can do with darcs, see http://darcs.net/manual/