2010-08-02 13:49:17 +02:00
|
|
|
fugitive: README
|
2010-07-24 04:25:34 +02:00
|
|
|
|
2010-07-25 18:52:35 +02:00
|
|
|
<h2 id="info">Info</h2>
|
2010-08-02 13:49:17 +02:00
|
|
|
|
2010-07-24 04:25:34 +02:00
|
|
|
<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>
|
2010-08-02 13:49:17 +02:00
|
|
|
<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 />
|
2010-08-08 19:47:19 +02:00
|
|
|
Moreover, everything that can be done using git, is.<br />
|
2010-08-02 13:49:17 +02:00
|
|
|
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>
|
2010-07-24 04:25:34 +02:00
|
|
|
|
2010-07-25 18:52:35 +02:00
|
|
|
<h2 id="install">Install</h2>
|
2010-07-24 04:25:34 +02:00
|
|
|
|
2010-08-02 13:49:17 +02:00
|
|
|
<h3 id="build">Build</h3>
|
2010-07-24 04:25:34 +02:00
|
|
|
<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 />
|
2010-07-24 13:22:39 +02:00
|
|
|
Then go in the newly created directory: <code>cd fugitive</code>, and
|
2010-07-24 04:25:34 +02:00
|
|
|
run the build script: <code>./build.sh</code>.
|
|
|
|
<br />
|
2010-08-02 13:49:17 +02:00
|
|
|
This will generate an executable file "fugitive" which you can use
|
|
|
|
to create your blog.
|
2010-07-24 04:25:34 +02:00
|
|
|
</p>
|
2010-08-02 13:49:17 +02:00
|
|
|
<h3 id="create">Create a blog</h3>
|
2010-07-24 04:25:34 +02:00
|
|
|
<p>
|
2010-08-02 13:49:17 +02:00
|
|
|
There's two install mode 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 file directly on
|
|
|
|
your server.
|
|
|
|
</p>
|
|
|
|
<p>
|
|
|
|
To create you blog run the commande:<br />
|
|
|
|
<code>fugitive --install-<em>mode</em> <dir></code>,
|
2010-08-10 20:32:11 +02:00
|
|
|
where <em>mode</em> is either "local" or "remote".
|
2010-07-24 04:25:34 +02:00
|
|
|
<br />
|
2010-08-02 13:49:17 +02:00
|
|
|
This will create the git repos with appropriate hooks, config and files in
|
2010-07-24 04:25:34 +02:00
|
|
|
<dir>.
|
|
|
|
<br />
|
|
|
|
If <dir> isn't specified then the current working directory is used.
|
2010-07-25 18:52:35 +02:00
|
|
|
</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>
|
2010-07-24 04:25:34 +02:00
|
|
|
|
2010-07-25 18:52:35 +02:00
|
|
|
<h2 id="config">Configuration</h2>
|
2010-07-24 04:25:34 +02:00
|
|
|
|
|
|
|
<p>
|
2010-07-25 18:52:35 +02:00
|
|
|
All this settings are in the "fugitive" section of the git config.
|
2010-08-02 13:49:17 +02:00
|
|
|
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:
|
2010-07-24 04:25:34 +02:00
|
|
|
</p>
|
2010-07-25 18:52:35 +02:00
|
|
|
<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 template's footer).
|
|
|
|
</dd>
|
2010-08-02 13:49:17 +02:00
|
|
|
<dt>public-dir*</dt>
|
2010-07-25 18:52:35 +02:00
|
|
|
<dd>
|
|
|
|
This is the path to the directory that will contain the generated html
|
2010-08-02 13:49:17 +02:00
|
|
|
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".
|
2010-07-25 18:52:35 +02:00
|
|
|
</dd>
|
2010-08-02 13:49:17 +02:00
|
|
|
<dt>articles-dir*</dt>
|
2010-07-25 18:52:35 +02:00
|
|
|
<dd>
|
|
|
|
This is the path where fugitive will look for published articles. Default
|
2010-08-02 13:49:17 +02:00
|
|
|
value is "_articles".
|
2010-07-25 18:52:35 +02:00
|
|
|
</dd>
|
2010-08-02 13:49:17 +02:00
|
|
|
<dt>templates-dire*</dt>
|
2010-07-25 18:52:35 +02:00
|
|
|
<dd>
|
|
|
|
This is the path where fugitive will look for templates files. Default
|
2010-08-02 13:49:17 +02:00
|
|
|
value is "_templates".
|
2010-07-25 18:52:35 +02:00
|
|
|
</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">
|
2010-08-02 13:49:17 +02:00
|
|
|
* 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.
|
2010-07-24 13:22:39 +02:00
|
|
|
</p>
|
2010-07-24 04:25:34 +02:00
|
|
|
|
2010-07-25 18:52:35 +02:00
|
|
|
<h2 id="usage">Usage</h2>
|
2010-07-24 04:25:34 +02:00
|
|
|
|
2010-08-02 13:49:17 +02:00
|
|
|
<h3 id="general-use">General use</h3>
|
2010-07-24 04:25:34 +02:00
|
|
|
<p>
|
|
|
|
Article you want to publish should be file without the .html extension in the
|
2010-08-08 19:47:19 +02:00
|
|
|
<em>articles-dir</em> directory (see <a href="#config">configuration</a>).
|
|
|
|
The first line of the file will be used as title and the rest of the file as
|
|
|
|
the content of the article.
|
2010-08-02 13:49:17 +02:00
|
|
|
</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>
|
2010-08-08 23:01:43 +02:00
|
|
|
When you commit change to a fugitive git repository, the post-commit hook
|
2010-08-08 21:48:50 +02:00
|
|
|
looks in the <em>articles-dir</em> directory
|
|
|
|
(see <a href="#config">configuration</a>) for newly added articles, modified
|
2010-08-10 20:32:11 +02:00
|
|
|
articles and deleted ones. Then it does the following things:
|
2010-08-08 21:48:50 +02:00
|
|
|
</p>
|
|
|
|
<ul>
|
|
|
|
<li>it generates static html files for newly added articles,</li>
|
|
|
|
<li>it regenerates static html files for modified artciles,</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" and "feed.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
|
2010-08-10 20:32:11 +02:00
|
|
|
everything is regenerated to make the change effective.
|
2010-07-24 04:25:34 +02:00
|
|
|
</p>
|
2010-08-10 20:32:11 +02:00
|
|
|
<p>
|
|
|
|
All generated files are created in the <em>public-dir</em> directory
|
|
|
|
(see <a href="#config">configuration</a>).
|
2010-07-24 04:25:34 +02:00
|
|
|
<p>
|
2010-08-02 13:49:17 +02:00
|
|
|
When you push to a remote repository installed with fugitive, the same thing
|
2010-08-10 20:32:11 +02:00
|
|
|
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
|
2010-08-02 13:49:17 +02:00
|
|
|
accordingly.
|
2010-07-24 04:25:34 +02:00
|
|
|
</p>
|
2010-07-25 18:52:35 +02:00
|
|
|
<p class="warning">
|
2010-08-02 13:49:17 +02:00
|
|
|
Do not create an article file named "archives".<br />
|
|
|
|
Do not create an article file named "index".
|
2010-07-24 04:25:34 +02:00
|
|
|
</p>
|
2010-08-02 13:49:17 +02:00
|
|
|
<h3 id="templating">Template system</h3>
|
2010-07-24 04:25:34 +02:00
|
|
|
<p><em>*TODO*</em></p>
|