github/repo2html
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
repo2html/README.md

8 KiB
Raw Blame History

repo2html

A command-line tool that generates a static HTML representation of a Git repository.

Page contents

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

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 a default.html file. Refer to assets/templates/default.html for an example default.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.

  1. Ensure you're in the repo2html git repository.
  2. As root, run make dependencies to install the required Chicken Scheme eggs.
  3. Run make to compile a static repo2html binary in the current directory.
  4. As root, run make install to copy the repo2html 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.

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 or
  • git 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 or
  • git 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 or
  • git 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.

Git Forge Software

Software for self-hosting or building your own collection of many git repos for potentially multiple users.

Git Forge Services

Third-party-hosted services that will host browsable code repositories.

Todos

  • documentation: provide a precompiled binary download
  • documentation/feature: use post-update rather than post-receive hook for simplicity
  • documentation: also describe use with post-commit hook
  • documentation: describe readme, license, and issues behaviours
  • feature: multi-page or collapse-able files list
  • feature: branches and releases (tags)
  • feature: diffs for each commit
  • feature: clickable line numbers in source files
  • feature: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.?
  • feature: syntax highlighting?
  • feature: markdown-render git log text
  • feature: other mechanisms for header id application like uniqueness checking, sequential numbering
  • feature: remotes, upstream identification, and tracking branch status