No frills static page generator for Git repositories
git clone https://git.8pit.net/depp.git
1## README 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.21.0 35* C compiler, pkg-config, … for linking against libgit2 36 37### Installation 38 39Clone the repository and ran the following commands: 40 41 $ make 42 $ sudo make install 43 44This will install two binaries: `depp` for generating HTML files on a 45per-repository basis and `depp-index` which can optionally be used to 46generate an HTML index page for listing all hosted git repositories. 47Both commands are further described in the provided man page, a usage 48example is provided below. 49 50### Usage 51 52Assuming you have a web server serving files located at 53`/var/www/htdocs/git.example.org`, you want 10 commits on the index 54page, and the repository can be cloned via `git://example.org/foo.git`: 55 56 $ depp -c 10 -u git://example.org/foo.git \ 57 -d /var/www/htdocs/git.example.org/foo \ 58 <path to git repository to generate pages for> 59 60To automate this process, create a `post-receive` hook for your 61repository on your git server, see `githooks(5)` for more information. 62Keep in mind that the repository page itself only needs to be regenerated 63if the default branch is pushed, since only the default branch is 64considered by `depp`. As such, an exemplary `post-receive` hook may look 65as follows: 66 67 #!/bin/sh 68 69 repo=$(git rev-parse --absolute-git-dir) 70 name=${repo##*/} 71 72 rebuild=0 73 defref=$(git symbolic-ref HEAD) 74 while read local_ref local_sha remote_ref remote_sha; do 75 if [ "${remote_ref}" = "${defref}" ]; then 76 rebuild=1 77 break 78 fi 79 done 80 81 # Only rebuild if a ref for the default ref was pushed 82 [ ${rebuild} -eq 1 ] || exit 0 83 84 depp -u "git://git.example.org/${name}" \ 85 -d "/var/www/htdocs/git.example.org/${name}" . 86 87If usage of `deep-index` is also desired, the index page can either be 88rebuild as part of the `post-receive` hook or in a separate cronjob. 89 90### README Rendering 91 92Rendering README files written in a chosen markup language (e.g. 93markdown) is supported. This is achieved by including an executable file 94called `git-render-readme` in the bare Git repository. When executed, 95this file receives the README content on standard input and must write 96plain HTML to standard output. 97 98As an example, consider the following `git-render-readme` script which 99uses the `markdown(1)` program provided by the [discount][discount website]100Markdown implementation:101102 #!/bin/sh103 exec markdown -f autolink104105### Caveats106107Existing HTML files are not tracked, thus the generated HTML for files108removed from the repository `HEAD` is not automatically removed from109the depp destination directory. In order to be able to identify HTML110files not touched by depp the `mtime` and `atime` of `index.html` is set111to a time *before* the generation of any HTML files on each invocation.112This allows removing generated HTML for files removed from the113repository by invoking the following command from the depp destination114directory:115116 $ find . -not -newer index.html -not -path ./index.html -type f \117 -exec rm {} \+ 2>/dev/null118119The above `find(1)` invocation can conveniently be executed from a120cronjob. Unfortunately, this command does not remove empty directories,121these need to be handled separately (some `find(1)` implementations122support `-empty` for this purpose).123124### License125126This program is free software: you can redistribute it and/or modify it127under the terms of the GNU General Public License as published by the128Free Software Foundation, either version 3 of the License, or (at your129option) any later version.130131This program is distributed in the hope that it will be useful, but132WITHOUT ANY WARRANTY; without even the implied warranty of133MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General134Public License for more details.135136You should have received a copy of the GNU General Public License along137with this program. If not, see <https://www.gnu.org/licenses/>.138139[cgit website]: https://git.zx2c4.com/cgit/140[gitweb website]: https://git-scm.com/docs/gitweb141[git-arr website]: https://blitiri.com.ar/p/git-arr/142[stagit website]: http://codemadness.nl/git/stagit/log.html143[libgit2 website]: https://libgit2.org/144[go website]: https://golang.org/145[discount website]: http://www.pell.portland.or.us/~orc/Code/discount/146[git2go repo]: https://github.com/libgit2/git2go147[git2go build]: https://github.com/libgit2/git2go#installing