Review request for: Let plugins influence what environment variables a wrapper will...
[ikiwiki] / doc / todo / git-annex_support.mdwn
1 A dear [[wishlist]] which would resolve [[this question|forum/ikiwiki_and_big_files]]: ikiwiki should support git-annex repositories.
2
3 I am not sure how this would work, but from my POV, it should do a `git annex get` when new commits are pushed to its bare repo. This would assume, of course, that there's another repo somewhere that ikiwiki has access to, which works for HTTP-style remotes, but could be more problematic for SSH remotes that require a key.
4
5 Another solution would be to make ikiwiki a remote itself and allow users to push big files to it. The only problem I see with this is those files would end up in the bare repository and not necessarily show up in the web rendering. Ideally, a big file pushed would be hardlinked between the two repos, but it seems [git-annex doesn't support that yet](http://git-annex.branchable.com/todo/wishlist:_use_hardlinks_for_local_clones). --[[anarcat]]
6
7 > One technical problem with this is that ikiwiki doesn't allow symlinks
8 > for [[security]], but git-annex relies on symlinks (unless you're in
9 > direct mode, but I'm not sure that's really desirable here).
10 > I'd like to make symlinks possible without compromising security,
11 > but it'll be necessary to be quite careful. --[[smcv]]
12
13 First implementation
14 ====================
15
16 So as the [[discussion]] shows, it seems it's perfectly possible to actually do this! There's this [gallery site](http://stockholm.kalleswork.net) which uses the [[plugins/contrib/album]] plugin and git-annex to manage its files.
17
18 The crucial steps are:
19
20  1. setup a git annex remote in `$srcdir`
21
22  2. configure direct mode because ikiwiki ignores symlinks for [[security]] reasons:
23
24         cd $srcdir
25         git annex init
26         git annex direct
27
28  3. configure files to be considered by git-annex (those will be not committed into git directly):
29
30         git config annex.largefiles 'largerthan=100kb and not (include=*.mdwn or include=*.txt)'
31
32  4. make the bare repository (the remote of `$srcdir`) ignored by git-annex:
33
34         cd $srcdir
35         git config remote.origin.annex-ignore true
36         git config remote.origin.annex-sync false
37
38     (!) This needs to be done on *ANY* clone of the repository, which is annoying, but it's important because we don't want to see git-annex stuff in the bare repo. (why?)
39
40  5. deploy the following crappy plugin to make commits work again and make sure the right files are added in git-annex:
41
42 [[!format perl """
43 #!/usr/bin/perl
44 package IkiWiki::Plugin::gitannex;
45
46 use warnings;
47 use strict;
48 use IkiWiki 3.00;
49
50 sub import {
51         hook(type => "getsetup", id => "gitannex", call => \&getsetup);
52         hook(type => "savestate", id => "gitannex", call => \&rcs_commit);
53         # we need to handle all rcs commands maybe?
54 }
55
56 sub getsetup () {
57         return
58                 plugin => {
59                         safe => 1, # rcs plugin
60                         rebuild => undef,
61                         section => "misc",
62                 },
63 }
64
65 # XXX: we want to copy or reuse safe_git
66
67 sub rcs_commit (@) {
68     chdir $config{srcdir};
69     `git annex add --auto`;
70     `git annex sync`;
71 }
72
73 sub rcs_commit_staged (@) {
74     rcs_commit($@);
75 }
76
77 1
78 """]]
79 This assumes you know what `srcdir`, `repository` and so on mean, if you forgot (like me), see this reference: [[rcs/git/]].
80
81
82 What doesn't work
83 -----------------
84
85  * the above plugin is kind of flaky and ugly.
86  * it's not an RCS plugin, but probably should be, replacing the git plugin, because really: git doesn't work at all anymore at this point
87
88 What remains to be clarified
89 ----------------------------
90
91  * how do files get pushed to the `$srcdir`? Only through the web interface?
92  * why do we ignore the bare repository?
93
94 See the [[discussion]] for a followup on that. --[[anarcat]]
95
96 Alternative implementation
97 ==========================
98
99 An alternative implementation, which remains to be detailed but is mentionned in [[forum/ikiwiki_and_big_files]], is to use the [[underlay]] feature combined with the `hardlink` option to deploy the git-annex'd files. Then git-annex is separate from the base ikiwiki git repo. --[[anarcat]]