mirror of
https://git.ludikovsky.name/git/fugitive.git
synced 2024-10-05 15:35:29 +02:00
426 lines
16 KiB
HTML
426 lines
16 KiB
HTML
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 http://clandest.in/fugitive 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 "fugitive" 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> <dir></code>,
|
|
where <em>mode</em> is either "local" or "remote".
|
|
<br />
|
|
This will create a git repository with appropriate hooks, config and files in
|
|
<dir>.
|
|
<br />
|
|
If <dir> 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 "fugitive" 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 "_public". You could set it to
|
|
"_public/blog" for instance if you want to have have a website in
|
|
"_public" and your blog in "/blog".
|
|
</dd>
|
|
<dt>articles-dir*</dt>
|
|
<dd>
|
|
This is the path where fugitive will look for published articles. Default
|
|
value is "_articles".
|
|
</dd>
|
|
<dt>templates-dir*</dt>
|
|
<dd>
|
|
This is the path where fugitive will look for templates files. Default
|
|
value is "_templates".
|
|
</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 "." neither have a '/' at the end. Example:
|
|
"dir/subdir" is valid but "./dir/subdir" and
|
|
"dir/subdir/" 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 "_drafts" 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
|
|
"previous" and "next" links alive),</li>
|
|
<li>it regenerates the archives.html, tags.html, atom.xml, and rss.xml
|
|
files,</li>
|
|
<li>and finally it copies the static html file of the last article to
|
|
"index.html".</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 "archives".<br />
|
|
Do not create an article file named "index".
|
|
</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><?fugitive <em>var</em> ?></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><!-- <em>var</em> --></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><?fugitive
|
|
include:<em>file</em> ?></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,
|
|
atom.xml, and rss.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><<span class="keyword">?fugitive</span> ifset:<em>var</em> ?>
|
|
Template code which is ignored if <em>var</em> value is empty, and
|
|
which typically includes <<span class="function-name">code</span>><<span class="keyword">?fugitive</span> <em>var</em> ?></<span class="function-name">code</span>>.
|
|
<<span class="keyword">?fugitive</span> endifset:<em>var</em> ?></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 "archives" in the archives.html template,
|
|
"feed" in the atom.xml and rss.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 "fugitive" 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 "[at]" and '.'
|
|
replaced by "(dot)").
|
|
</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><time></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><time></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><time></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 "[at]" and '.' replaced
|
|
by "(dot)").
|
|
</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 "[at]" and '.' replaced by
|
|
"(dot)").
|
|
</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, atom.xml, and rss.xml:</h4>
|
|
<p>
|
|
Two foreach loops are available: <code>foreach:article</code>
|
|
and <code>foreach:commit</code>. The syntax is as follows:
|
|
</p>
|
|
<pre><<span class="keyword">?fugitive</span> foreach:article ?>
|
|
Template code that will be repeated for each article and
|
|
where the values of <<span class="function-name">code</span>>article_*</<span class="function-name">code</span>> variables are
|
|
set in accordance with the article each time.
|
|
<<span class="keyword">?fugitive</span> endforeach:article ?></pre>
|
|
<pre><<span class="keyword">?fugitive</span> foreach:commit ?>
|
|
Template code that will be repeated for each commit and
|
|
where the values of <<span class="function-name">code</span>>commit_*</<span class="function-name">code</span>> variables are
|
|
set in accordance with the commit each time.
|
|
<<span class="keyword">?fugitive</span> endforeach:commit ?></pre>
|
|
<p>
|
|
The only difference between the archives.html, atom.xml, and rss.xml
|
|
templates is that in atom.xml and rss.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 <dir></code>, where <dir> 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>
|