1# depp23No frills static page generator for Git repositories.45## Motivation67Dynamic git repository viewers like [cgit][cgit website] or8[gitweb][gitweb website] inherit the general disadvantages of dynamic9web applications (resource consumption, security concerns, …). For this10reason, static page generators for git (e.g. [git-arr][git-arr website]11or [stagit][stagit website]) emerged recently. However, these page12generators are usually not compatible with large repository as they13generate lots of HTML files (e.g. one for each commit).1415Contrary to existing static page generator approaches, this software16does 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, thereby18allowing users to decide whether it is interesting enough to be cloned.19As such, this software does intentionally not provide a web frontend for20existing tools like `git-log(1)`, `git-blame(1)`, et cetera. If more21information is needed, the user should simply clone the repository and22use `git(1)` as usual.2324## Status2526I use this for my own Git server, it presently doesn't have any known27bugs and the currently implemented feature set works quite well.2829## Dependencies3031This software has the following dependencies:3233* [libgit2][libgit2 website] >= 1.534* [Go][go website] >= 1.16.0 (`embed` package needed)35* C compiler, pkg-config, … for linking against libgit23637## Installation3839This program can be installed using `go install`, it requires the go40toolchain to be setup correctly and `$GOPATH` to be set. If go is41configured correctly, simply run the following command:4243 $ go install github.com/nmeum/depp/...@latest4445To ease packaging, a `GNUmakfile` is also provided which automatically46installs the binary and the available documentation files to the47appropriate locations.4849In either case, two binaries will be installed: `depp` for generating50HTML files on a per-repository basis and `depp-index` which can51optionally be used to generate an HTML index page for listing all hosted52git repositories. Both commands are further described in the provided53man page, a usage example is provided below.5455## Usage5657Assuming you have a web server serving files located at58`/var/www/htdocs/git.example.org`, you want 10 commits on the index59page, and the repository can be cloned via `git://example.org/foo.git`:6061 $ 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>6465To automate this process, create a `post-receive` hook for your66repository on your git server, see `githooks(5)` for more information.67Keep in mind that the repository page itself only needs to be regenerated68if the default branch is pushed, since only the default branch is69considered by `depp`. As such, an exemplary `post-receive` hook may look70as follows:7172 #!/bin/sh7374 repo=$(git rev-parse --absolute-git-dir)75 name=${repo##*/}7677 rebuild=078 defref=$(git symbolic-ref HEAD)79 while read local_ref local_sha remote_ref remote_sha; do80 if [ "${remote_ref}" = "${defref}" ]; then81 rebuild=182 break83 fi84 done8586 # Only rebuild if a ref for the default ref was pushed87 [ ${rebuild} -eq 1 ] || exit 08889 depp -u "git://git.example.org/${name}" \90 -d "/var/www/htdocs/git.example.org/${name}" .9192If usage of `deep-index` is also desired, the index page can either be93rebuild as part of the `post-receive` hook or in a separate cronjob.9495## README Rendering9697Rendering README files written in a chosen markup language (e.g.98markdown) is supported. This is achieved by including an executable file99called `git-render-readme` in the bare Git repository. When executed,100this file receives the README content on standard input and must write101plain HTML to standard output.102103As an example, consider the following `git-render-readme` script which104uses the `markdown(1)` program provided by the [discount][discount website]105Markdown implementation:106107 #!/bin/sh108 exec markdown -f autolink109110## Caveats111112Existing HTML files are not tracked, thus the generated HTML for files113removed from the repository `HEAD` is not automatically removed from114the depp destination directory. In order to be able to identify HTML115files not touched by depp the `mtime` and `atime` of `index.html` is set116to a time *before* the generation of any HTML files on each invocation.117This allows removing generated HTML for files removed from the118repository by invoking the following command from the depp destination119directory:120121 $ find . -not -newer index.html -not -path ./index.html -type f \122 -exec rm {} \+ 2>/dev/null123124The above `find(1)` invocation can conveniently be executed from a125cronjob. Unfortunately, this command does not remove empty directories,126these need to be handled separately (some `find(1)` implementations127support `-empty` for this purpose).128129## License130131This program is free software: you can redistribute it and/or modify it132under the terms of the GNU General Public License as published by the133Free Software Foundation, either version 3 of the License, or (at your134option) any later version.135136This program is distributed in the hope that it will be useful, but137WITHOUT ANY WARRANTY; without even the implied warranty of138MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General139Public License for more details.140141You should have received a copy of the GNU General Public License along142with this program. If not, see <https://www.gnu.org/licenses/>.143144[cgit website]: https://git.zx2c4.com/cgit/145[gitweb website]: https://git-scm.com/docs/gitweb146[git-arr website]: https://blitiri.com.ar/p/git-arr/147[stagit website]: http://codemadness.nl/git/stagit/log.html148[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/git2go152[git2go build]: https://github.com/libgit2/git2go#installing