summaryrefslogtreecommitdiff
path: root/README.html
blob: 72d2b69fd59e7cbe5558a1083443470b7e388371 (plain)
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
fugitive: README

<h2 id="info">Info</h2>

<p>
  fugitive is a blog engine running on top of git using hooks to generate
  static html pages and thus having only git as dependency.
</p>
<p>
  In its hooks, fugitive uses only standard UNIX® tools that are included in
  the GNU core-utils package, plus sh as script interpreter. That's it.<br />
  Moreover, everything that can be done using git, is.<br />
  No dependencies like rack, heroku, or whatever Ruby gems you can think of. No
  configuration files. No metadata in your articles files. Hell, if you want to
  you could even make a <a href="#templating">template</a> that use git log as
  storage backend, which means <em>no files</em> either, just and only git.
</p>

<h2 id="install">Install</h2>

<h3 id="build">Build</h3>
<p>
  If you want to build fugitive from the source, clone the git repository:
  <br />
  <code>git clone git://gitorious.org/fugitive/fugitive.git fugitive</code>
  <br />
  Then go in the newly created directory: <code>cd fugitive</code>, and
  run the build script: <code>./build.sh</code>.
  <br />
  This will generate an executable file &quot;fugitive&quot; which you can use
  to create your blog.
</p>
<h3 id="create">Create a blog</h3>
<p>
  There are two install modes for fugitive: local and remote. The local mode
  should be used to install a repository where you edit your blog, and the
  remote mode for a repository to which you're going to push to publish your
  blog.<br />
  The local mode can also be used to publish if you edit your files directly on
  your server.
</p>
<p>
  To create your blog run the command:<br />
  <code>fugitive --install-<em>mode</em> &lt;dir&gt;</code>,
  where <em>mode</em> is either &quot;local&quot; or &quot;remote&quot;.
  <br />
  This will create a git repository with appropriate hooks, config and files in
  &lt;dir&gt;.
  <br />
  If &lt;dir&gt; isn't specified then the current working directory is used.
</p>
<p class="important">
  Once you have installed your blog you need to set the <em>blog-url</em>
  parameter in your git configuration. See <a href="#config">configuration</a>
  for details.
</p>

<h2 id="config">Configuration</h2>

<p>
  All these settings are in the &quot;fugitive&quot; section of the git config.
  You can change them with the command <br />
  <code>git config fugitive.<em>parameter</em> <em>value</em></code>,
  where <em>parameter</em> is one of the following:
</p>
<dl>
  <dt>blog-url</dt>
  <dd>
    This is the public URL of the generated blog. <strong>You need to set
    it</strong> as soon as possible since it's required for the RSS feed (and
    used in the default footer template).
  </dd>
  <dt>public-dir*</dt>
  <dd>
    This is the path to the directory that will contain the generated html
    files. Default value is &quot;_public&quot;. You could set it to
    &quot;_public/blog&quot; for instance if you want to have have a website in
    &quot;_public&quot; and your blog in &quot;/blog&quot;.
  </dd>
  <dt>articles-dir*</dt>
  <dd>
    This is the path where fugitive will look for published articles. Default
    value is &quot;_articles&quot;.
  </dd>
  <dt>templates-dir*</dt>
  <dd>
    This is the path where fugitive will look for templates files. Default
    value is &quot;_templates&quot;.
  </dd>
  <dt>preproc</dt>
  <dd>
    If you want your article to be preprocessed by an external tool (markdown,
    textile...) you need to set <em>preproc</em> to a command line that will
    read on stdin and write to stdout.
  </dd>
</dl>
<p class="note">
  * Those paths are relative to the root of the git repository, must be in it
  and must not start with &quot;.&quot; neither have a '/' at the end. Example:
  &quot;dir/subdir&quot; is valid but &quot;./dir/subdir&quot; and
  &quot;dir/subdir/&quot; are not.
</p>

<h2 id="usage">Usage</h2>

<h3 id="general-use">General use</h3>
<p>
  Articles you want to publish should be a file without the .html extension in the
  <em>articles-dir</em> directory (see <a href="#config">configuration</a>).
  The first line of the file will be used as a title and the rest of the file as
  the content of the article.
</p>
<p>
  By default there's a &quot;_drafts&quot; directory in which you can put
  articles you are writing and you want to version control in your git
  repository but you don't want to publish yet.
</p>
<p>
  When you commit change to a fugitive git repository, the post-commit hook
  looks in the <em>articles-dir</em> directory
  (see <a href="#config">configuration</a>) for newly added articles, modified
  articles and deleted ones. Then it does the following things:
</p>
<ul>
  <li>it generates static html files for newly added articles,</li>
  <li>it regenerates static html files for modified articles,</li>
  <li>it deletes static html files for deleted articles,</li>
  <li>it regenerates static html files for articles that are just before and
  after newly added and deleted articles (this to maintain the
  &quot;previous&quot; and &quot;next&quot; links alive),</li>
  <li>it regenerates the archives.html, tags.html, and feed.xml files,</li>
  <li>and finally it copies the static html file of the last article to
  &quot;index.html&quot;.</li>
</ul>
<p class="note">
  If a change happen in the <em>templates-dir</em> directory
  (see <a href="#config">configuration</a>), then static html files for
  everything is regenerated to make the change effective.
</p>
<p>
  All generated files are created in the <em>public-dir</em> directory
  (see <a href="#config">configuration</a>).
<p>
  When you push to a remote repository installed with fugitive, the same thing
  will happen but instead of looking only at the last commit, the hook will
  analyse every changes since the last push and then (re)generate html files
  accordingly.
</p>
<p class="warning">
  Do not create an article file named &quot;archives&quot;.<br />
  Do not create an article file named &quot;index&quot;.
</p>
<h3 id="templating">Template system</h3>
<p>
  The better explanation about the templates system is to see what the default
  templates looks like. But since they do not use all the offered
  possibilities, here are some more explanations...
</p>
<p>
  The fugitive template system uses xml preprocessor
  syntax: <code>&lt;?fugitive <em>var</em> ?&gt;</code> is rendered as the
  value of <em>var</em>. This choice has been made because with this syntax
  templates are still valid xml (and html) document, and it is semantically
  more accurate than xml comments (<code>&lt;!-- <em>var</em> --&gt;</code>).
</p>
<p>
  In addition to variable rendering, there is a conditional and a foreach loop
  constructs, plus an include directive.
</p>
<p>
  The syntax of the include directive is <code>&lt;?fugitive
  include:<em>file</em> ?&gt;</code> where <em>file</em> is relative to
  the <em>templates-dir</em> directory
  (see <a href="#config">configuration</a>). The includes are processed before
  anything else.
</p>
<p>
  The foreach loop construct is specific to the archives.html, tags.html, and
  feed.xml templates and will therefore be described at the same time. Where
  available, the loops are processed right after the includes.
</p>
<p>
  The syntax of the conditional construct is as follows:
</p>
<pre>&lt;<span class="keyword">?fugitive</span> ifset:<em>var</em> ?&gt;
  Template code which is ignored if <em>var</em> value is empty, and
  which typically includes &lt;<span class="function-name">code</span>&gt;&lt;<span class="keyword">?fugitive</span> <em>var</em> ?&gt;&lt;/<span class="function-name">code</span>&gt;.
&lt;<span class="keyword">?fugitive</span> endifset:<em>var</em> ?&gt;</pre>
<p class="note">
  Not every variable can be used in the conditional construct, this is indicated
  in the description of those which can't.
</p>
<p>The following variables are available everywhere:</p>
<dl>
  <dt>page_title</dt>
  <dd>
    Its value is &quot;archives&quot; in the archives.html template,
    &quot;feed&quot; in the feed.xml template, or the article title in the
    article.html template.
  </dd>
  <dt>blog_url</dt>
  <dd>
    The <em>blog-url</em> value in the &quot;fugitive&quot; section of the git
    configuration (see <a href="#config">configuration</a>).
  </dd>
  <dt>commit_Hash</dt>
  <dd>
    Its value is the hash corresponding to the last commit that provoked the
    (re)generation of the file.
  </dd>
  <p class="note">
    This is case-sensitive. Compare this with the next one.
  </p>
  <dt>commit_hash</dt>
  <dd>
    Its value is the short hash (the seven first digit of the hash)
    corresponding to the last commit that provoked the (re)generation of the
    file.
  </dd>
  <dt>commit_author</dt>
  <dd>
    Its value is the name of the author of the last commit that provoked the
    (re)generation of the file.
  </dd>
  <dt>commit_author_email</dt>
  <dd>
    Its value is the email of the author of the last commit that provoked the
    (re)generation of the file (with '@' replaced by &quot;[at]&quot; and '.'
    replaced by &quot;(dot)&quot;).
  </dd>
  <dt>commit_datetime</dt>
  <dd>
    Its value is the date and time of the last commit that provoked the
    (re)generation of the file.
  </dd>
  <dt>commit_datetime_html5</dt>
  <dd>
    Its value is the date and time of the last commit that provoked the
    (re)generation of the file, <em>but in an html5 <code>&lt;time&gt;</code>
    compliant format</em>.
  </dd>
  <dt>commit_date</dt>
  <dd>
    Its value is the date of the last commit that provoked the (re)generation
    of the file.
  </dd>
  <dt>commit_time</dt>
  <dd>
    Its value is the time of the last commit that provoked the (re)generation
    of the file.
  </dd>
  <dt>commit_timestamp</dt>
  <dd>
    Its value is the unix timestamp of the last commit that provoked the
    (re)generation of the file.
  </dd>
  <dt>commit_subject</dt>
  <dd>
    Its value is the subject (first line of the commit message) of the last
    commit that provoked the (re)generation of the file.
  </dd>
  <dt>commit_body</dt>
  <dd>
    Its value is the body (the rest of the commit message) of the last commit
    that provoked the (re)generation of the file. <strong>This variable can't
    be used in the conditional construct.</strong>
  </dd>
  <dt>commit_slug</dt>
  <dd>
    Its value is the subject of the last commit that provoked the
    (re)generation of the file but formatted to be file name friendly.
  </dd>
</dl>
<h4>Variables specific to the article.html template:</h4>
<dl>
  <dt>article_title</dt>
  <dd>
    Its value is the title of the article (the first line of the file).
  </dd>
  <dt>article_content</dt>
  <dd>
    Its value is the content of the article (the rest of the
    file). <strong>This variable can't be used in the conditional
    construct.</strong>
  </dd>
  <dt>article_file</dt>
  <dd>
    Its value is the file name of the article (without the .html extension).
  </dd>
  <dt>article_cdatetime</dt>
  <dd>
    Its value is the date and time of the publication of the article (the date
    of the commit which added the article to the repository in
    the <em>articles-dir</em> directory
    (see <a href="#config">configuration</a>)).
  </dd>
  <dt>article_cdatetime_html5</dt>
  <dd>
    Same as previous, but in an html5 <code>&lt;time&gt;</code> compliant
    format.
  </dd>
  <dt>article_cdate</dt>
  <dd>
    Its value is the date of the publication of the article.
  </dd>
  <dt>article_ctime</dt>
  <dd>
    Its value is the time of the publication of the article.
  </dd>
  <dt>article_ctimestamp</dt>
  <dd>
    Its value is the timestamp of the publication of the article.
  </dd>
  <dt>article_mdatetime</dt>
  <dd>
    Its value is the date and time of the last modification of the article
    (the date of the last commit which changed the article file).
  </dd>
  <dt>article_mdatetime_html5</dt>
  <dd>
    Same as previous, but in an html5 <code>&lt;time&gt;</code> compliant
    format.
  </dd>
  <dt>article_mdate</dt>
  <dd>
    Its value is the date of the last modification of the article.
  </dd>
  <dt>article_mtime</dt>
  <dd>
    Its value is the time of the last modification of the article.
  </dd>
  <dt>article_mtimestamp</dt>
  <dd>
    Its value is the timestamp of the last modification of the article.
  </dd>
  <dt>article_cauthor</dt>
  <dd>
    Its value is the author of the commit which added the article to the
    repository.
  </dd>
  <dt>article_cauthor_email</dt>
  <dd>
    Its value is the email of the author of the commit which added the article
    to the repository (with '@' replaced by &quot;[at]&quot; and '.' replaced
    by &quot;(dot)&quot;).
  </dd>
  <dt>article_mauthor</dt>
  <dd>
    Its value is the author of the last commit which changed the article file.
  </dd>
  <dt>article_mauthor_email</dt>
  <dd>
    Its value is the email of the author of the last commit which changed the
    article file (with '@' replaced by &quot;[at]&quot; and '.' replaced by
    &quot;(dot)&quot;).
  </dd>
  <dt>article_previous_file</dt>
  <dd>
    Its value is the file name (without .html extension) of the previous
    article ordered by publication date.
  </dd>
  <dt>article_previous_title</dt>
  <dd>
    Its value is the title of the previous article ordered by publication date.
  </dd>
  <dt>article_next_file</dt>
  <dd>
    Its value is the file name (without .html extension) of the next article
    ordered by publication date.
  </dd>
  <dt>article_next_title</dt>
  <dd>
    Its value is the title of the next article ordered by publication date.
  </dd>
</dl>
<h4>foreach loops in archives.html and feed.xml:</h4>
<p>
  Two foreach loops are available: <code>foreach:article</code>
  and <code>foreach:commit</code>. The syntax is as follows:
</p>
<pre>&lt;<span class="keyword">?fugitive</span> foreach:article ?&gt;
  Template code that will be repeated for each article and
  where the values of &lt;<span class="function-name">code</span>&gt;article_*&lt;/<span class="function-name">code</span>&gt; variables are
  set in accordance with the article each time.
&lt;<span class="keyword">?fugitive</span> endforeach:article ?&gt;</pre>
<pre>&lt;<span class="keyword">?fugitive</span> foreach:commit ?&gt;
  Template code that will be repeated for each commit and
  where the values of &lt;<span class="function-name">code</span>&gt;commit_*&lt;/<span class="function-name">code</span>&gt; variables are
  set in accordance with the commit each time.
&lt;<span class="keyword">?fugitive</span> endforeach:commit ?&gt;</pre>
<p>
  The only difference between the archives.html and feed.xml templates is that
  in feed.xml these constructs only loop on the five last articles and commits.
</p>

<h2 id="hacking">Hacking fugitive</h2>
<p>
  If you want to hack fugitive code to customize the behavior of the hooks, you
  can either edit the hooks directly in your fugitive blog repository, or edit
  them in the fugitive source code, then rebuild the <code>fugitive</code>
  executable using the <code>build.sh</code> script provided in the source code
  repository.
</p>
<p>
  In the latter case and if you already have a fugitive blog running, you'll
  need to install the new hooks. This can be done by running the command:<br />
  <code>fugitive --install-hooks &lt;dir&gt;</code>, where &lt;dir&gt; is the
  path to your fugitive blog repository, if it isn't specified then the current
  working directory is used.
</p>
<p>
  This can be handy if you decide for instance that you want to have the
  last <em>n</em> articles on your index.html page rather than a mere copy of
  the last article.
</p>

<h2 id="issues">Known issues</h2>
<p>
  There seems to be some issues with the version of git provided in Debian
  Lenny (1.5.*), I didn't investigate it yet, and I don't know if I'll do it,
  because at this time Squeeze is already frozen and git 1.7.* is available in
  the backports which are now officially supported by Debian.
</p>