No frills, single binary, static page generator for Git repositories.
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.
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.
Apart from a Go toolchain this software has no external dependencies.
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.
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:https://example.org/foo.git:
$ depp -c 10 -u git:https://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:https://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.
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
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).
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/.