depp

  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.
 99
100### README Rendering
101
102Rendering README files written in a chosen markup language (e.g.
103markdown) is supported. This is achieved by including an executable file
104called `git-render-readme` in the bare Git repository. When executed,
105this file receives the README content on standard input and must write
106plain HTML to standard output.
107
108As an example, consider the following `git-render-readme` script which
109uses the `markdown(1)` program provided by the [discount][discount website]
110Markdown implementation:
111
112	#!/bin/sh
113	exec markdown -f autolink
114
115### License
116
117This program is free software: you can redistribute it and/or modify it
118under the terms of the GNU General Public License as published by the
119Free Software Foundation, either version 3 of the License, or (at your
120option) any later version.
121
122This program is distributed in the hope that it will be useful, but
123WITHOUT ANY WARRANTY; without even the implied warranty of
124MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
125Public License for more details.
126
127You should have received a copy of the GNU General Public License along
128with this program. If not, see <https://www.gnu.org/licenses/>.
129
130[stagit website]: http://codemadness.nl/git/stagit/log.html
131[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/embed
137[go-git github]: https://github.com/go-git/go-git