github/repo2html
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
repo2html/README.md
m455 907516d1d6 Updated documentation and cleaned up directory tree 
- Updated documentation, so it's very nice for pho4cexa <3
- Moved helper/example files to an assets directory (feel free to
  rearrange all of these again if you have any better ideas :D
- Renamed and moved tutorial file to make it more descriptive
- Removed old environment variables from post-receive hook example file
2022-12-20 00:56:30 -05:00

5.2 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.

Configuration

You can repo2html by changing the following items:

Templates

You can customize repo2html by editing the assets/templates/default.html, and then specifying the path to the default.html file as the second command-line argument when running repo2html.

For example, if you placed a default.html file in ~/bin/templates, and you serve HTML files from /var/www/git, then you run repo2html /var/www/git ~/bin/templates.

Environment variables

You can provide a generic description by setting the REPO2HTML_DESCRIPTION environment variable, or by adding a description in a description file in the root directory of your Git repository.

Setting up a Git forge on your web server

Refer to Create a Git forge with repo2html to learn how use repo2html as a post-receive hook to auto-generate HTML webpages for bare Git repositories on a remote web server.

Alternative Git-to-HTML tools

Existing Git forges

Existing Git forge software

GitLab Gogs Gitea cgit GitWeb legit

Todos

  • 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: 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