diff options
| author | bringert <bringert@cs.chalmers.se> | 2005-11-17 14:57:23 +0000 |
|---|---|---|
| committer | bringert <bringert@cs.chalmers.se> | 2005-11-17 14:57:23 +0000 |
| commit | 2e808d442d89166272466a9a10dbfd635cd57dc5 (patch) | |
| tree | 01138706d24d29a9ae41354146dd2ed4a5ae0dcc /doc/darcs.html | |
| parent | fc0316e7aefd97ae6b452a8b1a02032c916ee29b (diff) | |
Some fixes in darcs.txt. Added darcs.html.
Diffstat (limited to 'doc/darcs.html')
| -rw-r--r-- | doc/darcs.html | 388 |
1 files changed, 388 insertions, 0 deletions
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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> +<META NAME="generator" CONTENT="http://txt2tags.sf.net"> +<TITLE>GF Darcs repository</TITLE> +</HEAD><BODY BGCOLOR="white" TEXT="black"> +<P ALIGN="center"><CENTER><H1>GF Darcs repository</H1> +<FONT SIZE="4"> +GF has now been moved to a Darcs repository. No changes should be committed to the CVS repository from now on. +</FONT></CENTER> + +<P></P> +<HR NOSHADE SIZE=1> +<P></P> + <UL> + <LI><A HREF="#toc1">What is darcs?</A> + <LI><A HREF="#toc2">How do I install Darcs?</A> + <LI><A HREF="#toc3">Read-only access</A> + <UL> + <LI><A HREF="#toc4">Getting a fresh copy for read-only access</A> + <LI><A HREF="#toc5">Updating your copy</A> + <LI><A HREF="#toc6">Submitting patches</A> + </UL> + <LI><A HREF="#toc7">Read-write access</A> + <UL> + <LI><A HREF="#toc8">Setting up your $PATH on the Chalmers system</A> + <LI><A HREF="#toc9">Setting up ssh alias and ControlMaster</A> + <LI><A HREF="#toc10">Setting up an ssh ControlMaster connection</A> + <LI><A HREF="#toc11">Getting a fresh copy</A> + <LI><A HREF="#toc12">Getting other people's changes?</A> + <LI><A HREF="#toc13">Commit your changes</A> + <LI><A HREF="#toc14">Apply a patch from someone else</A> + </UL> + <LI><A HREF="#toc15">Troubleshooting</A> + <UL> + <LI><A HREF="#toc16">I get the error "darcs not found" when pushing</A> + <LI><A HREF="#toc17">I get the error "(sftp) failed to fetch files."</A> + <LI><A HREF="#toc18">I get the error "Not a repository: gfreposerver:..."</A> + <LI><A HREF="#toc19">How do I avoid typing in my password so many times?</A> + <UL> + <LI><A HREF="#toc20">Using ssh ControlMaster</A> + <LI><A HREF="#toc21">Using ssh-agent</A> + </UL> + </UL> + <LI><A HREF="#toc22">Further information about Darcs</A> + </UL> + +<P></P> +<HR NOSHADE SIZE=1> +<P></P> +<A NAME="toc1"></A> +<H1>What is darcs?</H1> +<P> +Darcs is a decentralized revision control system. These are some of +the reasons for switching GF from CVS to Darcs: +</P> +<UL> +<LI>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. +<P></P> +<LI>we can provide read-only access over HTTP using the existing CS web server. +<P></P> +<LI>it is possible and easy to rename and remove both files and directories. +</UL> + +<P> +For more information about Darcs, see <A HREF="http://darcs.net/">http://darcs.net/</A> +</P> +<A NAME="toc2"></A> +<H1>How do I install Darcs?</H1> +<P> +There are precompiled packages for many platforms available at +<A HREF="http://darcs.net/DarcsWiki/CategoryBinaries">http://darcs.net/DarcsWiki/CategoryBinaries</A>. +</P> +<P> +There is also source code if you want to compile it yourself. Darcs is +written in Haskell and you need GHC to compile it. +</P> +<A NAME="toc3"></A> +<H1>Read-only access</H1> +<A NAME="toc4"></A> +<H2>Getting a fresh copy for read-only access</H2> +<P> +Anyone can get the latest development version of GF by running (all on one line): +</P> +<PRE> + $ darcs get --partial --set-scripts-executable http://www.cs.chalmers.se/Cs/Research/Language-technology/darcs/GF/ +</PRE> +<P></P> +<P> +This will create a directory called <CODE>GF</CODE> in the current +directory. See <CODE>GF/src/INSTALL</CODE> for instructions on compiling. The +main difference to compiling a GF release from sources is that you +need to run <CODE>autoconf</CODE> before <CODE>configure</CODE>. +</P> +<A NAME="toc5"></A> +<H2>Updating your copy</H2> +<P> +Get all new patches from the main repo: +</P> +<PRE> + $ darcs pull -a +</PRE> +<P></P> +<P> +Without <CODE>-a</CODE>, you can choose which patches you want to get. +</P> +<A NAME="toc6"></A> +<H2>Submitting patches</H2> +<P> +If you are using read-only access, send your patches by email to +someone with write-access. Create the patch with: +</P> +<PRE> + $ darcs send -o mypatch.patch +</PRE> +<P></P> +<P> +(where <CODE>mypatch</CODE> 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 <CODE>-o mypatch.patch</CODE> with +<CODE>--to=EMAIL</CODE> where <CODE>EMAIL</CODE> is the address to send it to. +</P> +<A NAME="toc7"></A> +<H1>Read-write access</H1> +<P> +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 <CODE>langtech</CODE> group to push changes to +the repository. +</P> +<A NAME="toc8"></A> +<H2>Setting up your $PATH on the Chalmers system</H2> +<P> +The <CODE>darcs</CODE> program has to be on your <CODE>$PATH</CODE> 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: +</P> +<PRE> + echo unsup >> $HOME/.vcs4/pathsetup +</PRE> +<P></P> +<P> +Note that the path setup works differently on different Chalmers machines. +The command above will setup you path on the newer machines correctly. +</P> +<A NAME="toc9"></A> +<H2>Setting up ssh alias and ControlMaster</H2> +<P> +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. +</P> +<P> +Add this to <CODE>~/.ssh/config</CODE> (create the file if it does not exist, +replace <CODE>bringert</CODE> with your own username on the +Chalmers system): +</P> +<PRE> + Host gfreposerver + HostName momo.medic.chalmers.se + User bringert + ControlPath /tmp/ssh-gfreposerver +</PRE> +<P></P> +<P> +This sets up an alias <CODE>gfreposerver</CODE> for the server we use +for the Darcs repository. Note that you really need to use +<CODE>momo.medic.chalmers.se</CODE> (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. +</P> +<P> +More information about the ControlMaster feature is available in +<CODE>man ssh_config</CODE>. +</P> +<A NAME="toc10"></A> +<H2>Setting up an ssh ControlMaster connection</H2> +<P> +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. +</P> +<P> +Start the master connection: +</P> +<PRE> + $ ssh -M gfreposerver +</PRE> +<P></P> +<P> +<B>NOTE: You need to have a ControlMaster connection running whenever you want to access the repo using ssh.</B> +You may want to create a script or alias for starting the connection. +</P> +<A NAME="toc11"></A> +<H2>Getting a fresh copy</H2> +<P> +Get your copy with (all on one line): +</P> +<PRE> + $ darcs get --partial --set-scripts-executable gfreposerver:/users/cs/www/Research/Language-technology/darcs/GF/ +</PRE> +<P></P> +<P> +The option <CODE>--partial</CODE> 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. +</P> +<A NAME="toc12"></A> +<H2>Getting other people's changes?</H2> +<P> +Get all new patches from the main repo: +</P> +<PRE> + $ darcs pull -a +</PRE> +<P></P> +<P> +Without <CODE>-a</CODE>, you can choose which patches you want to get. +</P> +<A NAME="toc13"></A> +<H2>Commit your changes</H2> +<P> +There are two steps to commiting a change to the main repo. First you +have to record the changes that you want to commit: +</P> +<PRE> + $ darcs record +</PRE> +<P></P> +<P> +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. +</P> +<P> +If you think there are too many questions about what to record, you +can use the <CODE>-a</CODE> flag to <CODE>record</CODE>. Or answer <CODE>a</CODE> to the first +question. Both of these record all the changes you have in your local +repository. +</P> +<P> +Then you can push the patch(es) to the main repo. If you are using +ssh-access, all you need to do is: +</P> +<PRE> + $ darcs push ``` +</PRE> +<P></P> +<P> +If you use the <CODE>-a</CODE> flag to push, all local patches which are not in +the main repo are pushed. +</P> +<A NAME="toc14"></A> +<H2>Apply a patch from someone else</H2> +<P> +Use: +</P> +<PRE> + $ darcs apply < mypatch.patch +</PRE> +<P></P> +<P> +This applies the patch to your local repository. To commit it to the +main repo, use <CODE>darcs push</CODE>. +</P> +<A NAME="toc15"></A> +<H1>Troubleshooting</H1> +<A NAME="toc16"></A> +<H2>I get the error "darcs not found" when pushing</H2> +<P> +If you get <CODE>darcs not found</CODE> when you try to push your changes, you +don't have darcs on your <CODE>$PATH</CODE> on the Chalmers system. See +the section above on setting up your <CODE>$PATH</CODE> on the Chalmers system. +</P> +<A NAME="toc17"></A> +<H2>I get the error "(sftp) failed to fetch files."</H2> +<P> +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. +</P> +<A NAME="toc18"></A> +<H2>I get the error "Not a repository: gfreposerver:..."</H2> +<P> +You get this error when you have set up ControlMaster, but don't have a master +connection running. Start a master connection: +</P> +<PRE> + $ ssh -M gfreposerver +</PRE> +<P></P> +<P> +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.: +</P> +<PRE> + $ ssh -M gfreposerver "bash -c 'while true; do echo -n .; sleep 30; done'" +</PRE> +<P></P> +<A NAME="toc19"></A> +<H2>How do I avoid typing in my password so many times?</H2> +<A NAME="toc20"></A> +<H3>Using ssh ControlMaster</H3> +<P> +See above. +</P> +<A NAME="toc21"></A> +<H3>Using ssh-agent</H3> +<P> +**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. ** +</P> +<P> +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. +</P> +<P> +Here is a guide to setting this up: +<A HREF="http://cfm.gs.washington.edu/security/ssh/client-pkauth/">http://cfm.gs.washington.edu/security/ssh/client-pkauth/</A> +</P> +<P> +Short summary (should on most modern Linux distros, maybe other +platforms too): +</P> +<P> +Generate a key pair: +</P> +<PRE> + $ 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: ... +</PRE> +<P></P> +<P> +Upload the public key to your Chalmers account (replace <CODE>bringert</CODE> with +your username): +</P> +<PRE> + $ ssh-copy-id -i ~/.ssh/id_rsa.pub bringert@remote.cs.chalmers.se +</PRE> +<P></P> +<P> +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): +</P> +<PRE> + $ ssh-add + Enter passphrase for /home/bjorn/.ssh/id_rsa: ... +</PRE> +<P></P> +<P> +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. +</P> +<P> +Try to use it to log in (with your own username again): +</P> +<PRE> + $ ssh bringert@remote.cs.chalmers.se + ... + zsh:bringert:[~]> +</PRE> +<P></P> +<A NAME="toc22"></A> +<H1>Further information about Darcs</H1> +<P> +For more info about what you can do with darcs, see <A HREF="http://darcs.net/manual/">http://darcs.net/manual/</A> +</P> + +<!-- html code generated by txt2tags 2.0 (http://txt2tags.sf.net) --> +<!-- cmdline: txt2tags -t html -\-toc darcs.txt --> +</BODY></HTML> |