doc/todo/mercurial.mdwn

   1 * Is the code sufficiently robust? It just warns when mercurial fails.
   2 * When rcs_commit is called with a $user that is an openid, it will be
   3   passed through to mercurial -u. Will mercurial choke on this?
   4  * Nope. Mercurial doesn't expect any particular format for the username,
   5    though "Name <address@domain>" is standard. --[[bma]]
   6 * The way `-u $user` is passed to `hg commit`, there's no way to tell
   7   if a given commit came in over the web or was done directly. So
   8   rcs_recentchanges hardcodes 'committype => "mercurial"'. See the monotone
   9   backend for an example of one that does this right.
  10 * The rcs_commit implementation seems not to notice if the file has been
  11   changed since a web edit started. Unlike all the other frontends, which
  12   use the rcstoken to detect if the web commit started editing an earlier
  13   version of the file, and if so, merge the two sets of changes together.
  14   It seems that with the current mercurial commit code, it will always
  15   blindly overwrite the current file with the web edited version, losing
  16   any other changes.
  17 * `rcs_commit_staged`, `rcs_rename`, `rcs_remove`, and `rcs_diff` are not
  18   implemented for mercurial, and so attachments, remove and rename plugins
  19   and recentchangesdiff cannot be used with it. (These should be fairly
  20   easy to add..)
  21
  22 Posthook: in `$srcdir/.hg/hgrc`, I have the following
  23
  24     [hooks]
  25     incoming.update = hg up
  26     update.ikiwiki = ikiwiki --setup /path/to/ikiwiki.setup --refresh
  27
  28 This should update the working directory and run ikiwiki every time a change is recorded (someone who knows mercurial better than I do may be able to suggest a better way, but this works for me.)
  29
  30 > Try running it with --post-commit instead of --refresh. That should
  31 > work better, handling both the case where the edit was made via the web
  32 > and then committed, and the case where a commit was made directly.
  33 > It can deadlock if the post-commit hook runs with --refresh in the
  34 > former case. --[[Joey]]
  35
  36 The problem with --post-commit is that if you delete some pages in $SRC, ikiwiki --setup setupfile --post-commit will not delete them in $DEST. --[[users/weakish]]
  37
  38 > You should really be using a setup file that has `mercurial_wrapper`
  39 > set, and running the wrapper generated by that from your hook.
  40 > That will work. I think that the `--setup --post-commit` on the command
  41 > line is currently broken and does the same expensive rebuild process as --setup
  42 > alone (which doesn't delete files from $DEST either). Will fix that.
  43 > (fixed)
  44 > --[[Joey]]
  45
  46 >> Mercurial doesn't support put hooks in .hg/hooks/* (like git). In Mercurial, the only way to run
  47 >> your own hooks is specifying them in the hgrc file. (Or write a new extension.)
  48 >> I guess use a very long command will work.
  49 >> (e.g. ikiwiki --post-commit --a-lot-of-switches --set var=value $SRC $DEST)
  50 >> (Fortunately ikiwiki supports --set var=value so without --setup works.)
  51 >>
  52 >> Alternative is always editing via cgi or pushing.  Never work on the $SRC/repo directly.
  53 >> --[[users/weakish]]
  54
  55 >>> I don't see anything preventing you from using a setup file with
  56 >>> `mercurial_wrapper => ".hg/ikiwiki-hook",` and then modifying the hgrc
  57 >>> to run that wrapper. --[[Joey]]
  58
  59 >> Thanks for pointing out this.  I have some stupid misunderstanding on the
  60 >> usage of mercurial_wrapper before.  The wrapper works nicely! --[[weakish]]
  61
  62 I add the following to .hg/hgrc:(I use changegroup since I don't think we need refresh per changeset, please point out if I am wrong.)
  63
  64     [hooks]
  65     changegroup = hg update >&2 && ikiwiki --setup path.to.setup.file --refresh
  66     post-commit = path.to.the.mercurial.wrapper
  67
  68 -----
  69
  70 I have no idea when the deadlock will happen.  --[[users/weakish]]
  71
  72 > For the deadlock to occur, a edit has to be made via the web.
  73 >
  74 > Ikiwiki,
  75 > running as a CGI, takes a lock on the wiki, and commits the edit,
  76 > continuing to run in the background, with the lock still held.
  77 > When the edit is committed, the hg hook runs, running `ikwiki --refresh`.
  78 > Nearly the first thing that process does it try to lock the wiki..
  79 > which is already locked. This lock is taken in a blocking manner,
  80 > thus the deadlock -- the cgi is waiting for the commit to finish before
  81 > dropping the lock, and the commit is blocked waiting for the lock to be
  82 > released.
  83 >
  84 > --post-commit avoids this problem by checking if the cgi is running
  85 > and avoiding doing anything in that case. (While still handing the
  86 > refresh if the commit was not made by the CGI.)
  87 > So in that case, the commit finishes w/o ikiwiki doing anything,
  88 > and the ikiwiki CGI handles the wiki refresh.
  89 > --[[Joey]]
  90
  91
  92 ***
  93
  94 I have a few notes on mercurial usage after trying it out for a while:
  95
  96 1. I have been using ikiwiki's `--post-commit` option without apparent problems. I'm the only current user of my wiki, though.
  97
  98 1. The `ikiwiki.setup` file included in ikiwiki works with mercurial's `hgserve`, which is not the preferred solution. Mercurial's `hgwebdir.cgi` is more flexible and doesn't require running a server. I have this in my .setup file:
  99
 100         # Mercurial stuff.
 101         rcs => "mercurial",
 102         historyurl => "http://localhost/cgi-bin/hgwebdir.cgi/ikiwiki/log/tip/\[[file]]",
 103         diffurl => "http://localhost/cgi-bin/hgwebdir.cgi/ikiwiki/diff/tip/\[[file]]",
 104
 105 1. I have noticed that running `ikiwiki` after a change to the wiki adds files to a directory called `recentchanges` under `$srcdir`. I don't understand why such files are needed; worse, they are not added to mercurial's list of tracked files, so they polute the output of `hg log`. Is this a bug? Should mercurial's commit hook be modified to add these files before the commit?
 106
 107 --buo
 108
 109 > No, those files should not be added to revision control. --[[Joey]]
 110
 111 >> OK. I see two problems:
 112
 113 >> 1. If I clone my wiki, I won't get an exact copy of it: I will lose the recentchanges history. This could be an acceptable limitation but IMO this should be documented.
 114
 115 >>> The history is stored in mercurial. How will it be lost?
 116
 117 >> 2. The output of `hg status` is polluted. This could be solved trivially by adding a line containing `recentchanges` to `.hgignore`. Another alternative would be to store the `recentchanges` directory inside `$srdcir/.ikiwiki`.
 118
 119 >> I think the ideal solution would be to build `$destdir/recentchanges/*` directly from the output of `hg log`. --[[buo]]
 120
 121 >>>> That would be 100 times as slow, so I chose not to do that. --[[Joey]]
 122
 123 >>>> Since this is confusing people, allow me to clarify: Ikiwiki's
 124 >>>> recentchanges generation pulls log information directly out of the VCS as
 125 >>>> needed. It caches it in recentchanges/* in the `scrdir`. These cache
 126 >>>> files need not be preserved, should never be checked into VCS, and if
 127 >>>> you want to you can configure your VCSignore file to ignore them,
 128 >>>> just as you can configure it to ignore the `.ikiwiki` directory in the
 129 >>>> `scrdir`. --[[Joey]]