gf-core/doc/darcs.txt

GF Darcs repository
Author: Björn Bringert <bringert@cs.chalmers.se>
Last update: %%date(%c)

% NOTE: this is a txt2tags file.
% Create an html file from this file using:
% txt2tags -t html --toc darcs.txt

%!target:html
%!options(html): --toc
%!encoding:utf-8

= What is darcs? =

Darcs is a decentralized revision control system. See http://darcs.net/ for more information.

= 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://code.haskell.org/gf/
```

This will create a directory called ``gf`` in the current
directory. See ``gf/src/INSTALL`` for instructions on compiling. The
main difference compared to compiling a GF release 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.

If you have added files, you first need to tell your local repository to 
keep them under revision control:

```
$ darcs add file1 file2 ...
```

To record changes, use:

```
$ 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.


== 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 a user account on code.haskell.org, you can get read-write access over SSH
to the GF repository. 
To get an account, [fill out this form http://community.haskell.org/admin/account_request.html].
Once you have an account, ask <bringert@cs.chalmers.se> to add you to the ``gf`` project.


== Getting a fresh copy ==

Get your copy with (all on one line),
replacing ``bringert`` with your own username on code.haskell.org:

```
$ darcs get --partial --set-scripts-executable bringert@code.haskell.org:/srv/code/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, then you push them
to the main repo.

For instructions on recording your changes locally,
see "Recording local changes" above.

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

= Further information about Darcs =


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