depp

No frills static page generator for Git repositories

git clone https://git.8pit.net/depp.git

  1# depp
  2
  3No frills static page generator for Git repositories.
  4
  5## Motivation
  6
  7Dynamic git repository viewers like [cgit][cgit website] or
  8[gitweb][gitweb website] inherit the general disadvantages of dynamic
  9web applications (resource consumption, security concerns, …). For this
 10reason, static page generators for git (e.g. [git-arr][git-arr website]
 11or [stagit][stagit website]) emerged recently. However, these page
 12generators are usually not compatible with large repository as they
 13generate lots of HTML files (e.g. one for each commit).
 14
 15Contrary to existing static page generator approaches, this software
 16does not strive to be a fully featured git browser for the web. Instead,
 17the idea is to provide a quick overview for a given repository, thereby
 18allowing users to decide whether it is interesting enough to be cloned.
 19As such, this software does intentionally not provide a web frontend for
 20existing tools like `git-log(1)`, `git-blame(1)`, et cetera. If more
 21information is needed, the user should simply clone the repository and
 22use `git(1)` as usual.
 23
 24## Status
 25
 26I use this for my own Git server, it presently doesn't have any known
 27bugs and the currently implemented feature set works quite well.
 28
 29## Dependencies
 30
 31This software has the following dependencies:
 32
 33* [libgit2][libgit2 website] >= 1.5
 34* [Go][go website] >= 1.16.0 (`embed` package needed)
 35* C compiler, pkg-config, … for linking against libgit2
 36
 37## Installation
 38
 39This program can be installed using `go install`, it requires the go
 40toolchain to be setup correctly and `$GOPATH` to be set. If go is
 41configured correctly, simply run the following command:
 42
 43	$ go install github.com/nmeum/depp/...@latest
 44
 45To ease packaging, a `GNUmakfile` is also provided which automatically
 46installs the binary and the available documentation files to the
 47appropriate locations.
 48
 49In either case, two binaries will be installed: `depp` for generating
 50HTML files on a per-repository basis and `depp-index` which can
 51optionally be used to generate an HTML index page for listing all hosted
 52git repositories. Both commands are further described in the provided
 53man page, a usage example is provided below.
 54
 55## Usage
 56
 57Assuming you have a web server serving files located at
 58`/var/www/htdocs/git.example.org`, you want 10 commits on the index
 59page, and the repository can be cloned via `git://example.org/foo.git`:
 60
 61	$ depp -c 10 -u git://example.org/foo.git \
 62		-d /var/www/htdocs/git.example.org/foo \
 63		<path to git repository to generate pages for>
 64
 65To automate this process, create a `post-receive` hook for your
 66repository on your git server, see `githooks(5)` for more information.
 67Keep in mind that the repository page itself only needs to be regenerated
 68if the default branch is pushed, since only the default branch is
 69considered by `depp`. As such, an exemplary `post-receive` hook may look
 70as follows:
 71
 72	#!/bin/sh
 73	
 74	repo=$(git rev-parse --absolute-git-dir)
 75	name=${repo##*/}
 76	
 77	rebuild=0
 78	defref=$(git symbolic-ref HEAD)
 79	while read local_ref local_sha remote_ref remote_sha; do
 80		if [ "${remote_ref}" = "${defref}" ]; then
 81			rebuild=1
 82			break
 83		fi
 84	done
 85	
 86	# Only rebuild if a ref for the default ref was pushed
 87	[ ${rebuild} -eq 1 ] || exit 0
 88	
 89	depp -u "git://git.example.org/${name}" \
 90		-d "/var/www/htdocs/git.example.org/${name}" .
 91
 92If usage of `deep-index` is also desired, the index page can either be
 93rebuild as part of the `post-receive` hook or in a separate cronjob.
 94
 95## README Rendering
 96
 97Rendering README files written in a chosen markup language (e.g.
 98markdown) is supported. This is achieved by including an executable file
 99called `git-render-readme` in the bare Git repository. When executed,
100this file receives the README content on standard input and must write
101plain HTML to standard output.
102
103As an example, consider the following `git-render-readme` script which
104uses the `markdown(1)` program provided by the [discount][discount website]
105Markdown implementation:
106
107	#!/bin/sh
108	exec markdown -f autolink
109
110## Caveats
111
112Existing HTML files are not tracked, thus the generated HTML for files
113removed from the repository `HEAD` is not automatically removed from
114the depp destination directory. In order to be able to identify HTML
115files not touched by depp the `mtime` and `atime` of `index.html` is set
116to a time *before* the generation of any HTML files on each invocation.
117This allows removing generated HTML for files removed from the
118repository by invoking the following command from the depp destination
119directory:
120
121	$ find . -not -newer index.html -not -path ./index.html -type f \
122		-exec rm {} \+ 2>/dev/null
123
124The above `find(1)` invocation can conveniently be executed from a
125cronjob. Unfortunately, this command does not remove empty directories,
126these need to be handled separately (some `find(1)` implementations
127support `-empty` for this purpose).
128
129## License
130
131This program is free software: you can redistribute it and/or modify it
132under the terms of the GNU General Public License as published by the
133Free Software Foundation, either version 3 of the License, or (at your
134option) any later version.
135
136This program is distributed in the hope that it will be useful, but
137WITHOUT ANY WARRANTY; without even the implied warranty of
138MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
139Public License for more details.
140
141You should have received a copy of the GNU General Public License along
142with this program. If not, see <https://www.gnu.org/licenses/>.
143
144[cgit website]: https://git.zx2c4.com/cgit/
145[gitweb website]: https://git-scm.com/docs/gitweb
146[git-arr website]: https://blitiri.com.ar/p/git-arr/
147[stagit website]: http://codemadness.nl/git/stagit/log.html
148[libgit2 website]: https://libgit2.org/
149[go website]: https://golang.org/
150[discount website]: http://www.pell.portland.or.us/~orc/Code/discount/
151[git2go repo]: https://github.com/libgit2/git2go
152[git2go build]: https://github.com/libgit2/git2go#installing