Docs used by hub.darcs.net (eg the front page). Fork this and add questions/answers to make it better. (http://hub.darcs.net)

root / frontpage.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
<div style="text-align:right;">
</div>

<script type="text/javascript">
$(document).ready(function() {

  $("h4").nextUntil("h3, h4").hide();
  // $("h4").first().nextUntil("h3, h4").show();

  $("#collapse-all").click(function() {
    $("h4").nextUntil("h3, h4").hide();
  });

  $("#expand-all").click(function() {
    $("h4").nextUntil("h3, h4").show();
  });

  $("h4").click(function( e ) {
    $( e.target ).nextUntil("h3, h4").toggle();
  });

  /* expand a question when following a link to it from this page.. hacky */
  $("a").click(function( e ) {
    var dest = $(e.target).attr('href');
    if (dest.substr(0,1)=='#')
	  $(dest).nextUntil("h3, h4").show();
  });

  if (window.location.hash) {
    $(window.location.hash).nextUntil("h3, h4").show();
  }

});
</script>

<style>

h3 { font-weight:normal; }

h4, #expand-all, #collapse-all { cursor:pointer; }

pre, code {
  background-color:white;
  border:none;
  color:black;
}

</style>

<h1 style="font-size:5em; margin-bottom:.2em;">darcs hub</h1>
<p style="font-size:1.3em;">simple version control and collaboration</p>
<!-- <p style="font-size:1.4em;">the place to host [darcs](#whats-darcs) repositories</p> -->
<!-- funding widget -->
<style>
#funding {
  float:right;
  text-align:center;
  margin:0 0 1em 1em;
  padding:10px 10px 10px 10px;
  border:thin solid #eee;
  border-radius:10px;
  max-width:15em;
}
#funding > table {
  white-space:nowrap;
  text-align:right;
  display:inline-block;
}
#funding > table td:first-child {
  padding-right:.5em;
}
.amount {
  font-weight:bold;
}
.negative {
  background-color:#fee;
}
.negative  a:link, .negative  a:visited {
  color:red;
}
.positive {
  background-color:#efe;
}
.positive  a:link, .positive  a:visited {
  color:green;
}
</style>
<div id="funding">
<p>
<!-- This site is supported by you! Become a darcs hub backer today. -->
<!-- Keep this site strong - become a darcs hub backer today! -->
<!-- A community service of Joyful Systems since 2012. -->
<!-- Thank you for your support. -->
Help this site grow - become a darcs hub backer today!

<div style="margin:0 0 1em 0;">
<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&amp;hosted_button_id=4XDT9VSTMFWP8"><img width=62 height=31 border=0 style="" src="https://www.paypal.com/en_US/i/btn/x-click-but04.gif" alt="donate via paypal"></a>
<!-- <a href="https://gratipay.com/darcs-hub/"><img border=0 src="http://img.shields.io/gratipay/darcs-hub.svg"></a> -->
<br>
<div style="margin-top:1em; display:inline-block; width:116px; height:70px;">
<script data-gratipay-teamslug="darcs-hub" src="https://grtp.co/v2.js" async></script>
</div>
<!-- <a href="https://opencollective.com/darcshub#support"><img src="https://opencollective.com/darcshub/backers/badge.svg" border="0"></a> -->
<!-- <a href="https://opencollective.com/darcshub#support"><img src="https://opencollective.com/darcshub/sponsors/badge.svg" border="0"></a> -->
</div>
<table>
 <tr><td>Profit/loss this month:</td><td class="positive amount"><a href="/simon/darcshub-docs#finances" title="updated manually, expect a short delay">  $87.30</a></td></tr>
 <tr><td>Profit/loss this year: </td><td class="negative amount"><a href="/simon/darcshub-docs#finances" title="updated manually, expect a short delay">-$472.70</a></td></tr>
 <tr><td>Current net worth:     </td><td class="negative amount"><a href="/simon/darcshub-docs#finances" title="updated manually, expect a short delay">-$472.70</a></td></tr>
</table>
</div>
<!-- funding widget end -->
darcs makes version control simple.
darcs hub provides easy repo hosting and collaboration for darcs users,
and is 100% FOSS software and a community service you can contribute to
(
[issues](/simon/darcsden/issues),
[code](/simon/darcsden),
[docs](/simon/darcshub-docs),
[finances](/simon/darcshub-docs#finances),
<!-- [finances](/simon/darcshub-docs/browse/darcshub.journal#66) -->
[news](/simon/darcshub-docs#news)
).
The philosophy here is *Less But Better*.
Enjoy the simplicity of darcs and darcs hub!

<br clear="all">
<a id="expand-all" title="Show all answers" style="float:right; font-size:small; margin-top:1em;">[expand all]</a>
<h2 style="border-bottom:thin solid black;">FAQ</h2>

### About

#### What's darcs?

<div style="float:right; margin:0 0 1em 1em;">
<img src="/public/images/darcs-logo.png" border=0 />
</div>
[Darcs](http://darcs.net) is a
[version control system](http://en.wikipedia.org/wiki/Revision_control),
broadly similar to Git, Mercurial and others, but with a simpler
conceptual model that many people find less costly to learn and use.
If you don't have a lot of time to spend learning your version control tool,
darcs (and darcs hub) may be a good choice.

#### What's darcs hub?

Darcs hub is the free darcs repository hosting site operated since 2012 by
[Simon Michael](http://joyful.com). It succeeds the older
patch-tag.com and darcsden.com sites. It aims to:

1. provide a reliable, usable and evolving hosting and collaboration hub for darcs users

2. accelerate the development of darcs and its ecosystem,
   eg through an easier contribution process and increased visibility and dogfooding.

#### What's darcsden?

darcs hub runs on free software, so you can [help](#how-can-i-help)
make it better (or run your own server).  That software is
[darcsden](/simon/darcsden), an evolution of the software originally
developed by Alex Suraci for darcsden.com.
 
<!-- #### How does it relate to darcsden.com and patch-tag.com? -->

<!-- This site is inspired by two fine projects: Thomas Hartmann's -->
<!-- [patch-tag.com](http://patch-tag.com) (currently hosting ~1000 public -->
<!-- repos), and Alex Suraci's [darcsden.com](http://darcsden.com) (currently -->
<!-- hosting ~200). I have contributed to both and know them pretty well.  Due -->
<!-- to their maintainers being busy elsewhere, both sites have reliability -->
<!-- problems and neither has been actively maintained or developed for some -->
<!-- time. This is unfortunate!  I believe the way forward is to maintain this -->
<!-- key piece of infrastructure closely alongside darcs itself, and turn the -->
<!-- dogfooding knobs up to 11. -->

<!-- Darcs hub runs an updated version of Alex Suraci's darcsden software. -->
<!-- The updates before 2012/9/15 excluding UI style tweaks were released -->
<!-- as darcsden 1.0 on Hackage. darcsden 1.1 and later include all darcs -->
<!-- hub-inspired changes, and can still be used for personal darcsden instances. -->


#### Can I rely on this site?

Darcs hub is currently an all-volunteer effort by
[Simon Michael](http://joyful.com) with help from the darcs
team. However it's robust enough to host your project and to depend on
for daily work.  We currently host about 800 users and 1600 repos.

Currently, the stability is that of a usable beta; you can expect a
serviceable UI, some functionality and performance limitations, decent
reliability, and no data loss.  Uptime and response time are checked
every minute (see link in the footer).

As with all cloud-based services, it's wise to
(a) keep your own backups of important data and
(b) assume no guarantee of security or privacy.
The site is hosted in the US.
We do our best and all improvements are welcome.

The [roadmap](/simon/darcshub-docs/#roadmap) gives some more overview.

#### What is the backup policy?

The VPS running hub.darcs.net and other sites is backed up nightly,
between 0100 and 0300 GMT-8, by
[Linode's backup system](http://library.linode.com/backup-service).
This keeps three backup images: the one from last night, the one from
last Sunday, and the one from the previous Sunday. In other words,
there is generally a backup that's one day old, and a backup that's 1-2
weeks old.

You should also keep your own backup(s) of your
repositories. Basically, keep one or more copies of the repo elsewhere
and up to date, using darcs get and darcs pull.
(If you decide to automate this, don't forget to plan for the scenario
where someone cracks your darcs hub account, logs in as you and
quietly obliterates or modifies your repos.)


#### How can I help?

- Use hub.darcs.net and provide bug reports and feedback

- Investigate and clarify [open issues](/simon/darcsden/issues)

- Test the setup process by setting up your own instance:

    1. get the <a href="/simon/darcsden">latest darcsden</a>
    2. get the required dependencies installed, perhaps disabling unnecessary bits with cabal build flags
    3. Build with `cabal build` or `make`
    4. Run as described in the README
    5. Investigate and report problems

- Contribute code and documentation patches.
  This is a fun project! It's a web app, so there's quick visual
  feedback. It's darcs-related, but easier to understand than darcs
  itself. Developers are online in #darcs, and useful changes will be
  quickly deployed to this site.

    1. fork hub's <a href="/simon/darcsden">darcsden</a> or <a href="/simon/hub.darcs.net">documentation</a> repos
    2. darcs get a local copy, make changes, push back to your fork. (Or, edit directly via the web.)
    3. Your changes will appear in hub's <a href="/simon/darcsden/patches">patch&nbsp;queue</a> and get
       merged and/or discussed on #darcs.

    See also the [project roadmap](/simon/hub.darcs.net/ROADMAP.md) and [planning board](/trello).

- Contribute feature/reliability/performance/installability/api
  improvements to darcsden's dependencies, especially
  [darcs](/darcs/darcs-screened),
  [highlighting-kate](https://github.com/jgm/highlighting-kate),
  [snap](https://github.com/snapframework/snap),
  and [hsp](/nibro/hsp).

#### What's new?

Here are darcs hub
[blog posts](http://joyful.com/tags/darcs.html),
[code changes](/simon/darcsden/changes) and
[doc changes](/simon/hub.darcs.net/changes).

Also each of the [repositories hosted here](/explore) has its own changes page and feed.
Here are a few interesting ones:
[darcs-reviewed](/darcs/darcs-reviewed/changes),
[darcs-screened](/darcs/darcs-screened/changes),
[darcs-wiki](/darcs/darcs-wiki/changes),
[darcsden](/simon/darcsden/changes),
[divine-mainline](/mornfall/divine-mainline/changes),
[dnplayer](/dbp/dnplayer/changes),
[globalscript](/jcast/globalscript/changes),
[happstack](/stepcut/happstack/changes),
[netwire](/ertes/netwire/changes)


### Pulling and pushing


#### How do I get a local copy of a repo?

Via HTTP - works for any public repo and requires no authentication. Examples:

    darcs get http://hub.darcs.net/OWNER/REPO
    darcs get http://hub.darcs.net/simon/darcsden

Or via SSH - works for any public repo, and private repos that you own or
are a member of. You'll need to [create an account](/register) and
[configure SSH access](#how-do-i-configure-ssh-access). Examples:

    darcs get [YOU@]hub.darcs.net:[OWNER/]REPO
    darcs get hub.darcs.net:simon/darcsden
    darcs get hub.darcs.net:myrepo

YOU is your darcs hub username; you can omit it if it's the same as your local username.
OWNER/ can be omitted if the repo is yours.


#### How do I pull new changes from hub.darcs.net?

Once you've got a local copy of a repo, you can merge any new changes
from the upstream repo on darcs hub by running:

    darcs pull

in your repo. It uses the original get address by default.


#### How do I push my changes back to hub.darcs.net?

Pushing requires SSH access. If you got the repo via SSH, just

    darcs push

If you got it via HTTP, you must
[configure ssh access](#how-do-i-configure-ssh-access) and then push
to the SSH address:

    darcs push [YOU@]hub.darcs.net:[OWNER/]REPO [--set-default]

The `--set-default` flag will make it remember this as the upstream
address, so you can just type `darcs push` in future.

#### How do I push to someone else's repo?

You can push to someone else's repo if they've added you as a repo member in the repo settings.
Otherwise, make a fork of their repo and push to that, so they can review and merge your changes themselves
(on their repo branches page).

#### How do I create and push to a new repo?

1. `ssh [YOU@]hub.darcs.net init REPO DESCRIPTION` (or: log in -> my repos -> new repo)
2. `darcs push -a [YOU@]hub.darcs.net:REPO`

#### How do I configure ssh access?

After (or while) [creating an account](/register), configure your
[ssh public key](https://hkn.eecs.berkeley.edu/~dhsu/ssh_public_key_howto.html)
in [user settings](/settings).  Then test your ssh
access and look for the following output, which indicates a successful
connection:

    $ ssh YOU@hub.darcs.net
	PTY allocation request failed on channel 0
    shell request failed on channel 0

You may be asked to authenticate our host key upon your first connection.

    The authenticity of host 'hub.darcs.net (173.255.219.222)' can't be established.
    RSA key fingerprint is MD5:31:b9:1c:ec:83:4d:fe:45:4d:9a:61:ba:f4:72:5c:eb.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added 'hub.darcs.net,173.255.219.222' (RSA) to the list of known hosts.

You should verify that the fingerprint presented to you is one of

    MD5:31:b9:1c:ec:83:4d:fe:45:4d:9a:61:ba:f4:72:5c:eb
    SHA256:C7v5yTl4PpF1QaXYM+rgccUGkik3XE7/VLjqCjcGIl8

You might need some additional configuration for your ssh client since
not all ssh features have been implemented in the
[darcsden ssh server](/simon/darcsden/browse/ssh-server/darcsden-ssh.hs) or
[ssh package](http://hackage.haskell.org/package/ssh) - symptoms
include complaints about X11Forwarding, darcs push failing with "Apply
Failed!",
<!-- [OpenSSH 7+ ssh failing to connect](http://irclog.perlgeek.de/darcs/2015-08-12) -->
etc.
Adding these custom settings to your ssh client's config file (`~/.ssh/config` on unix)
may help:

    Host hub.darcs.net
       ControlMaster no
       ForwardAgent no
       ForwardX11 no

Prior to 2017/3/12, it was [recommended](http://hub.darcs.net/simon/darcsden/issue/140)
to add `KexAlgorithms +diffie-hellman-group1-sha1`; this is no longer needed 
and should be removed.

### More

#### What are repo members ?

In your repo's settings, you can add other darcs hub users as members.
They will be able to push to your repo (but not delete changes from
it, nor change its settings), and view it even if it's private.

#### How do I delete changes from my hub repo?

    ssh [YOU@]hub.darcs.net obliterate REPO

This runs `darcs obliterate` in your repo on hub, prompting
interactively for each change, most recently pushed first. You must be
the repo owner, not just a member.  Options like `--dry-run` are not
supported, so you'll sometimes have to figure out which later
depending patches also need to be selected for obliteration.  Another
option is to obliterate locally, then delete the hub repo and
re-publish it.

Obliterate rewrites your repo's history, so be mindful - if others
have forked your repo and you obliterate, they'll need to do the same
or the change will show up again in your branches page.


#### How do I view a file's raw content ?

Click the file name in the page heading. Currently this forces the text/plain content type.


#### How do I get a feed of a repo's changes ?

Add `/atom` to the changes url. Eg
[http://hub.darcs.net/simon/darcsden/changes/atom](/simon/darcsden/changes/atom).

#### How do I tell a repo owner that I have some patches they may like to pull?

After pushing some patches to your fork of someone's repo, those
patches will automatically appear in the branches page of the parent
repo. However, the parent repo's owner may not notice. Currently there
are two ways to notify them:

1. track down their email or IRC name and ping them. Eg look for a
   nick in #darcs matching their hub username, or check the READMEs in
   their public repos.

2. if the parent repo has its darcs hub issue tracker enabled, you can
   open a new issue and attach your new patches as a bundle - this will
   send them a notification email

#### Can I reference or close issues with a commit ?

When a patch is pushed to an issue-tracker-enabled repo, and the patch
name contains a reference to an open issue, that issue will be closed
automatically, and the commit will be mentioned in an issue comment. Here is the
[syntax](http://hub.darcs.net/simon/darcsden/browse/post-hook/darcsden-post-hook.hs#90).
Some valid examples:

```
some patch (closes #1)
resolves #52, blah blah
this fixes #100 I think
```

I think the following are not yet supported:

- the issue comment should link to the commit
- referencing/commenting an issue without closing it
- closing multiple issues at once




<h3></h3>
<br>
More questions ? Ask on [#darcs](http://darcs.net/IRC) and/or [add to the FAQ](http://hub.darcs.net/simon/darcshub-docs).