7.5 KiB
repo2html
A command-line tool that generates a static HTML representation of a Git repository.
Page contents
- Features
- Requirements
- Usage
- Installation
- Configuration
- Creating a Git forge on your web server
- Alternative Git-to-HTML tools
- Existing Git forges
- Existing Git forge software
- Todos
Features
- Static html files
- Customizable templates
- Can be used as a standalone command-line tool, or in a Git hook
- Built-in, plaintext issue support
- Image support
- Markdown files are rendered as HTML
- No resident background process
Requirements
- Chicken Scheme
- The following Chicken Scheme eggs:
- Git
Usage
repo2html <destination> <template-directory>
Run repo2html
inside the root directory of a Git repository or a bare Git
repository.
<destination>
is the path to the directory that you want the HTML files to be generated in.<template-directory>
is the path to the directory that contains adefault.html
file. Refer toassets/templates/default.html
for an exampledefault.html
file.
The HTML that's generated represents the state of the HEAD
commit, not the
current state of the work tree.
Installation
This section guides you through installing the required dependencies, compiling
a binary, and then installing the binary. By default, repo2html
installs
into the /usr/local/bin
directory.
- Ensure you're in the
repo2html
git repository. - As root, run
make dependencies
to install the required Chicken Scheme eggs. - Run
make
to compile a staticrepo2html
binary in the current directory. - As root, run
make install
to copy therepo2html
binary into the/usr/local/bin
directory.
Note: If you want to use main.scm
as the repo2html
executable, instead
of compiling a static binary file, then run
cp main.scm /usr/local/bin/repo2html
as root.
Templates
You can customize repo2html
by modifying the template file
assets/templates/default.html
, and then specifying the directory containing
your modified default.html
as the second command-line argument when running
repo2html
.
For example, if you placed a default.html
template file in
~/var/templates
, and you serve HTML files from /var/www/git
, then you run
repo2html /var/www/git ~/var/templates
.
Templates are rendered using ersatz, whose syntax is similar to the Jinja2 templating system.
If you use the include
directive in your modified default.html
template
file, repo2html
will look for the templates to be included in that same
specified directory, where your default.html
template lives.
The following variables are available to templates:
source_files_list
: a list of all the files in the repo.repository_description
: a short description of the repo, if provided. See configuration.repository_name
: the name of the repo. See configuration.repository_path
: the URL path from the forge root to the repo.repository_path_parent
: repository_path without the repo itself.repository_ancestors
: a list of each path element in repository_path_parent.readme_file
: the filename of the README file, if any. used for the "about" link.license_file
: the filename of the LICENSE file, if any. used for the "license" link.issues_file
: if any files exist in ISSUES/, this will be set to "ISSUES".repo2html_version
: the blob hash of main.scm in this repository.source_file
: the filename of the file being rendered.root
: always empty. # TODO FIXMEelements
: a list of each path element leading to the file being rendered.basename
: the filename being rendered, with one extension removed.extension
: the extension removed in basename.relative_root
:html/
if the current file is/index.html
otherwise empty.
Configuration
repo2html
understands the following configuration settings.
These settings are typically set using git config
like
git config repo2html.<setting> value
Environment variables may also be used for configuration, and take precedence over settings in git config
:
export REPO2HTML_<SETTING>=value
Name
$REPO2HTML_NAME
orgit config repo2html.name
- default: the repo's directory name
Your repository "name" is, by default, the name of the directory as specified in the first argument provided to repo2html
.
You may override this if you prefer a more human-friendly name, for example:
git config repo2html.name "Git Repository To Hypertext Markup Language Generator"
This affects the template variable repository_name
but not repository_path
.
Description
$REPO2HTML_DESCRIPTION
orgit config repo2html.description
or- edit the
.git/description
file - default: ""
A short description for the repo.
This may also be set by adding a description in a description
file in the root directory of your Git repository.
(This is the same mechanism that cgit
uses.)
ForgeRoot
$REPO2HTML_FORGEROOT
orgit config repo2html.forgeroot
This is a helper intended for use when building a git forge.
It specifies the filesystem path to the directory containing (possibly a hierarchy of) html output directories.
This affects the template variables repository_path
, repository_path_parent
, and repository_ancestors
, when the repo is found to be in a subdirectory of ForgeRoot
.
Example:
With forgeroot unset, the command
repo2html /var/www/repos/mike/projecta/repo1 /path/to/templates
will set the variable repository_path
to repo1
With forgeroot set to /var/www/repos
, the command
repo2html /var/www/repos/mike/projecta/repo1 /path/to/templates
will set the variable repository_path
to mike/projecta/repo1
When your forge is built with a shared git user, it's convenient to use --global to specify this just once, like:
sudo -u git git config --global repo2html.forgeroot /var/git-repos/
Creating a Git forge on your web server
Refer to
Create a Git forge with repo2html
to learn how use repo2html
in a post-receive
hook to auto-generate HTML
representations of bare Git repositories on a remote web server after you git push
to them.
Alternatives
Git Repo Static Page Generators
Other tools like repo2html
, that generate a set of HTML files representing the contents of a git repository.