depp

commits

Clone the repository to access all 255 commits.

• cmd/
• css/
• gitweb/
• man/
• GNUmakefile
• LICENSE.md
• README.md
• go.mod
• go.sum

README

No frills, single binary, static page generator for Git repositories.

Motivation

Contrary to existing static page generator approaches, this software does not strive to be a fully featured git browser for the web. Instead, the idea is to provide a quick overview for a given repository, thereby allowing users to decide whether it is interesting enough to be cloned. As such, this software does intentionally not provide a web frontend for existing tools like git-log(1), git-blame(1), et cetera. If more information is needed, the user should simply clone the repository and use git(1) as usual.

Further, this page generator is entirely written in Go using the pure Go Git library go-git instead of libgit2 to interact with Git repositories. Thereby, allowing the implementation to be compiled as a single statically linked binary while also embedding all HTML and CSS files into the binary through Go’s embed package.

Status

I use this for my own Git server, it presently doesn’t have any known bugs and the currently implemented feature set works quite well.

Dependencies

Apart from a Go toolchain this software has no external dependencies.

Installation

Clone the repository and ran the following commands:

$ make
$ sudo make install

This will install two binaries: depp for generating HTML files on a per-repository basis and depp-index which can optionally be used to generate an HTML index page for listing all hosted git repositories. Both commands are further described in the provided man page, a usage example is provided below.

Usage

Assuming you have a web server serving files located at /var/www/htdocs/git.example.org, you want 10 commits on the index page, and the repository can be cloned via git://example.org/foo.git:

$ depp -c 10 -u git://example.org/foo.git \
    -d /var/www/htdocs/git.example.org/foo \
    <path to git repository to generate pages for>

To automate this process, create a post-receive hook for your repository on your git server, see githooks(5) for more information. Keep in mind that the repository page itself only needs to be regenerated if the default branch is pushed, since only the default branch is considered by depp. As such, an exemplary post-receive hook may look as follows:

#!/bin/sh

repo=$(git rev-parse --absolute-git-dir)
name=${repo##*/}

rebuild=0
defref=$(git symbolic-ref HEAD)
while read local_ref local_sha remote_ref remote_sha; do
    if [ "${remote_ref}" = "${defref}" ]; then
        rebuild=1
        break
    fi
done

# Only rebuild if a ref for the default ref was pushed
[ ${rebuild} -eq 1 ] || exit 0

depp -u "git://git.example.org/${name}" \
    -d "/var/www/htdocs/git.example.org/${name}" .

If usage of deep-index is also desired, the index page can either be rebuild as part of the post-receive hook or in a separate cronjob.

README Rendering

Rendering README files written in a chosen markup language (e.g. markdown) is supported. This is achieved by including an executable file called git-render-readme in the bare Git repository. When executed, this file receives the README content on standard input and must write plain HTML to standard output.

As an example, consider the following git-render-readme script which uses the markdown(1) program provided by the discount Markdown implementation:

#!/bin/sh
exec markdown -f autolink

Caveats

Existing HTML files are not tracked, thus the generated HTML for files removed from the repository HEAD is not automatically removed from the depp destination directory. In order to be able to identify HTML files not touched by depp the mtime and atime of index.html is set to a time before the generation of any HTML files on each invocation. This allows removing generated HTML for files removed from the repository by invoking the following command from the depp destination directory:

$ find . -not -newer index.html -not -path ./index.html -type f \
    -exec rm {} \+ 2>/dev/null

The above find(1) invocation can conveniently be executed from a cronjob. Unfortunately, this command does not remove empty directories, these need to be handled separately (some find(1) implementations support -empty for this purpose).

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.