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 7Contrary to existing static [page][stagit website] [generator][depp website] 8approaches, this software does not strive to be a fully featured git browser 9for the web. Instead, the idea is to provide a quick overview for a given 10repository, thereby allowing users to decide whether it is interesting enough 11to be cloned. As such, this software does intentionally not provide a web 12frontend for existing tools like `git-log(1)`, `git-blame(1)`, et cetera. If 13more information is needed, the user should simply clone the repository and use 14`git(1)` as usual. 15 16Further, this page generator is entirely written in Go using the pure Go Git 17library [go-git][go-git github] instead of [libgit2][libgit2 website] to 18interact with Git repositories. Thereby, allowing the implementation to be 19compiled as a single statically linked binary while also embedding all HTML and 20CSS files into the binary through Go's [embed][go embed] package. 21 22### Features 23 24* Easy to deploy, everything is backed into the binaries (no external dependencies). 25* Blazingly fast as it only rebuilds files that changed since the last invocation. 26* Simple and mobile-friendly web design which can be easily customized. 27 28### Status 29 30I use this for my own [Git server][8pit git]. I am presently not aware of any 31bugs and consider it mostly finished software. As I use it myself, I am 32committed to maintaining it for the foreseeable future. 33 34### Installation 35 36Installation requires a [Go toolchain][go website]. Assuming a supported Go is 37available, the software can be installed either via `go install` or `make`. 38Both methods will install two binaries: `depp` for generating HTML files on a 39per-repository basis and `depp-index` which can optionally be used to generate 40an HTML index page for listing all hosted git repositories. Both commands are 41further described in the provided man page, a usage example is provided below. 42 43#### go install 44 45To install to the program using `go install` run the following command: 46 47 $ go install github.com/nmeum/depp/...@latest 48 49Note that this will not install additional documentation files, e.g. man pages. 50 51#### make 52 53Clone the repository manually and ran the following commands: 54 55 $ make 56 $ sudo make install 57 58This is the preferred method when packaging this software for a distribution. 59 60### Usage 61 62Assuming you have a web server serving files located at 63`/var/www/htdocs/git.example.org`, you want 10 commits on the index 64page, and the repository can be cloned via `git://example.org/foo.git`: 65 66 $ depp -c 10 -u git://example.org/foo.git \ 67 -d /var/www/htdocs/git.example.org/foo \ 68 <path to git repository to generate pages for> 69 70To automate this process, create a `post-receive` hook for your 71repository on your git server, see `githooks(5)` for more information. 72Keep in mind that the repository page itself only needs to be regenerated 73if the default branch is pushed, since only the default branch is 74considered by `depp`. As such, an exemplary `post-receive` hook may look 75as follows: 76 77 #!/bin/sh 78 79 repo=$(git rev-parse --absolute-git-dir) 80 name=${repo##*/} 81 82 rebuild=0 83 defref=$(git symbolic-ref HEAD) 84 while read local_ref local_sha remote_ref remote_sha; do 85 if [ "${remote_ref}" = "${defref}" ]; then 86 rebuild=1 87 break 88 fi 89 done 90 91 # Only rebuild the HTML if the default ref was pushed. 92 [ ${rebuild} -eq 1 ] || exit 0 93 94 depp -u "git://git.example.org/${name}" \ 95 -d "/var/www/htdocs/git.example.org/${name}" . 96 97If usage of `deep-index` is also desired, the index page can either be 98rebuild as part of the `post-receive` hook or in a separate cronjob. 99100### README Rendering101102Rendering README files written in a chosen markup language (e.g.103markdown) is supported. This is achieved by including an executable file104called `git-render-readme` in the bare Git repository. When executed,105this file receives the README content on standard input and must write106plain HTML to standard output.107108As an example, consider the following `git-render-readme` script which109uses the `markdown(1)` program provided by the [discount][discount website]110Markdown implementation:111112 #!/bin/sh113 exec markdown -f autolink114115### License116117This program is free software: you can redistribute it and/or modify it118under the terms of the GNU General Public License as published by the119Free Software Foundation, either version 3 of the License, or (at your120option) any later version.121122This program is distributed in the hope that it will be useful, but123WITHOUT ANY WARRANTY; without even the implied warranty of124MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General125Public License for more details.126127You should have received a copy of the GNU General Public License along128with this program. If not, see <https://www.gnu.org/licenses/>.129130[stagit website]: http://codemadness.nl/git/stagit/log.html131[depp website]: https://depp.brause.cc/depp/132[libgit2 website]: https://libgit2.org/133[8pit git]: https://git.8pit.net/134[go website]: https://golang.org/135[discount website]: http://www.pell.portland.or.us/~orc/Code/discount/136[go embed]: https://pkg.go.dev/embed137[go-git github]: https://github.com/go-git/go-git