From 2e808d442d89166272466a9a10dbfd635cd57dc5 Mon Sep 17 00:00:00 2001 From: bringert Date: Thu, 17 Nov 2005 14:57:23 +0000 Subject: [PATCH] Some fixes in darcs.txt. Added darcs.html. --- doc/darcs.html | 388 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/darcs.txt | 78 ++++++---- 2 files changed, 439 insertions(+), 27 deletions(-) create mode 100644 doc/darcs.html diff --git a/doc/darcs.html b/doc/darcs.html new file mode 100644 index 000000000..a2c189ae4 --- /dev/null +++ b/doc/darcs.html @@ -0,0 +1,388 @@ + + + + +GF Darcs repository + +

GF Darcs repository

+ +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: +

+ + +

+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

+

+Get all new patches from the main repo: +

+
+  $ darcs pull -a
+
+

+

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

+ +

Submitting patches

+

+If you are using read-only access, send your patches by email to +someone with write-access. Create the patch with: +

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

+

+(where mypatch is hopefully replaced by a slightly more +descriptive name). 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. +

+ +

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: +

+
+  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. +

+

+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
+
+

+

+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. +

+ +

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 you +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, and be prepared to enter your password many times, +or use the ssh ControlMaster feature as desctribed 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
+
+

+

+If your master connection keeps dying because of inactivity, you can have it +run some program with outputs something once in a while, e.g.: +

+
+  $ ssh -M gfreposerver "bash -c 'while true; do echo -n .; sleep 30; done'"
+
+

+ +

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 MEDIC's new systems, such as + momo.medic.chalmers.se since MEDIC has decided to disable public key + authentication on all new machines. ** +

+

+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:[~]>
+
+

+ +

Further information about Darcs

+

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

+ + + + diff --git a/doc/darcs.txt b/doc/darcs.txt index 85ad6e80e..6875b3b98 100644 --- a/doc/darcs.txt +++ b/doc/darcs.txt @@ -3,6 +3,11 @@ GF Darcs repository GF has now been moved to a Darcs repository. No changes should be committed to the CVS repository from now on. +% NOTE: this is a txt2tags file. +% Create an html file from this file using: +% txt2tags -t html --toc darcs.txt + + = What is darcs? = Darcs is a decentralized revision control system. These are some of @@ -61,6 +66,7 @@ $ darcs pull -a Without ``-a``, you can choose which patches you want to get. + == Submitting patches == If you are using read-only access, send your patches by email to @@ -82,6 +88,24 @@ patch directly from darcs. If so, replace ``-o mypatch.patch`` with = 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. + +== 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: + +``` +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 @@ -97,19 +121,20 @@ Chalmers system): Host gfreposerver HostName momo.medic.chalmers.se User bringert -ControlPath /tmp/bringert@momo.medic.chalmers.se:22 +ControlPath /tmp/ssh-gfreposerver ``` -This sets up an alias ``gfreposerver`` for the machine we use -to access the Darcs repository. Note that you really need to use +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. +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``. +More information about the ControlMaster feature is available in +``man ssh_config``. -== Setting up an ssh connection == +== 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 @@ -121,10 +146,12 @@ Start the master connection: $ ssh -M gfreposerver ``` +**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. + == Getting a fresh copy == -If you have an account on the Chalmers system and want read-write -access, you can get your copy with (all on one line): +Get your copy with (all on one line): ``` $ darcs get --partial --set-scripts-executable gfreposerver:/users/cs/www/Research/Language-technology/darcs/GF/ @@ -175,9 +202,6 @@ ssh-access, all you need to do is: If you use the ``-a`` flag to push, all local patches which are not in the main repo are pushed. -You need to be a member of the ``langtech`` group to push to the -repository. - == Apply a patch from someone else == @@ -194,6 +218,12 @@ 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 @@ -218,18 +248,18 @@ $ ssh -M gfreposerver "bash -c 'while true; do echo -n .; sleep 30; done'" ``` -= How do I avoid typing in my password so many times? = +== How do I avoid typing in my password so many times? == -== Using ssh ControlMaster == +=== Using ssh ControlMaster === See above. -== Using ssh-agent == +=== Using ssh-agent === -*NOTE: the method below will not work with MEDIC's new systems, such as +**NOTE: the method below will not work with MEDIC's new systems, such as momo.medic.chalmers.se since MEDIC has decided to disable public key - authentication on all new machines. * + authentication on all new machines. ** 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 @@ -279,18 +309,12 @@ $ ssh bringert@remote.cs.chalmers.se zsh:bringert:[~]> ``` -= I get "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. To fix -this, log in to your Chalmers account and run: - -``` -echo unsup >> $HOME/.vcs4/pathsetup -``` -= Further information = + += Further information about Darcs = For more info about what you can do with darcs, see http://darcs.net/manual/ + +