Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nmeum/depp

No frills static page generator for Git repositories
https://github.com/nmeum/depp

git go static-site-generator

Last synced: 3 months ago
JSON representation

No frills static page generator for Git repositories

Awesome Lists containing this project

README 

        
## README



No frills static page generator for Git repositories.



### Motivation



Dynamic git repository viewers like [cgit][cgit website] or

[gitweb][gitweb website] inherit the general disadvantages of dynamic

web applications (resource consumption, security concerns, …). For this

reason, static page generators for git (e.g. [git-arr][git-arr website]

or [stagit][stagit website]) emerged recently. However, these page

generators are usually not compatible with large repository as they

generate lots of HTML files (e.g. one for each commit).



Contrary to existing static page generator approaches, this software

does not strive to be a fully featured git browser for the web. Instead,

the idea is to provide a quick overview for a given repository, thereby

allowing users to decide whether it is interesting enough to be cloned.

As such, this software does intentionally not provide a web frontend for

existing tools like `git-log(1)`, `git-blame(1)`, et cetera. If more

information is needed, the user should simply clone the repository and

use `git(1)` as usual.



### Status



I use this for my own Git server, it presently doesn't have any known

bugs and the currently implemented feature set works quite well.



### Dependencies



This software has the following dependencies:



* [libgit2][libgit2 website] >= 1.5

* [Go][go website] >= 1.21.0

* C compiler, pkg-config, … for linking against libgit2



### Installation



Clone the repository and ran the following commands:



    $ make

    $ sudo make install



This will install two binaries: `depp` for generating HTML files on a

per-repository basis and `depp-index` which can optionally be used to

generate an HTML index page for listing all hosted git repositories.

Both commands are further described in the provided man page, a usage

example is provided below.



### Usage



Assuming you have a web server serving files located at

`/var/www/htdocs/git.example.org`, you want 10 commits on the index

page, and the repository can be cloned via `git://example.org/foo.git`:



	$ depp -c 10 -u git://example.org/foo.git \

		-d /var/www/htdocs/git.example.org/foo \

		



To automate this process, create a `post-receive` hook for your

repository on your git server, see `githooks(5)` for more information.

Keep in mind that the repository page itself only needs to be regenerated

if the default branch is pushed, since only the default branch is

considered by `depp`. As such, an exemplary `post-receive` hook may look

as follows:



	#!/bin/sh

	

	repo=$(git rev-parse --absolute-git-dir)

	name=${repo##*/}

	

	rebuild=0

	defref=$(git symbolic-ref HEAD)

	while read local_ref local_sha remote_ref remote_sha; do

		if [ "${remote_ref}" = "${defref}" ]; then

			rebuild=1

			break

		fi

	done

	

	# Only rebuild if a ref for the default ref was pushed

	[ ${rebuild} -eq 1 ] || exit 0

	

	depp -u "git://git.example.org/${name}" \

		-d "/var/www/htdocs/git.example.org/${name}" .



If usage of `deep-index` is also desired, the index page can either be

rebuild as part of the `post-receive` hook or in a separate cronjob.



### README Rendering



Rendering README files written in a chosen markup language (e.g.

markdown) is supported. This is achieved by including an executable file

called `git-render-readme` in the bare Git repository. When executed,

this file receives the README content on standard input and must write

plain HTML to standard output.



As an example, consider the following `git-render-readme` script which

uses the `markdown(1)` program provided by the [discount][discount website]

Markdown implementation:



	#!/bin/sh

	exec markdown -f autolink



### Caveats



Existing HTML files are not tracked, thus the generated HTML for files

removed from the repository `HEAD` is not automatically removed from

the depp destination directory. In order to be able to identify HTML

files not touched by depp the `mtime` and `atime` of `index.html` is set

to a time *before* the generation of any HTML files on each invocation.

This allows removing generated HTML for files removed from the

repository by invoking the following command from the depp destination

directory:



	$ find . -not -newer index.html -not -path ./index.html -type f \

		-exec rm {} \+ 2>/dev/null



The above `find(1)` invocation can conveniently be executed from a

cronjob. Unfortunately, this command does not remove empty directories,

these need to be handled separately (some `find(1)` implementations

support `-empty` for this purpose).



### License



This program is free software: you can redistribute it and/or modify it

under the terms of the GNU General Public License as published by the

Free Software Foundation, either version 3 of the License, or (at your

option) any later version.



This program is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General

Public License for more details.



You should have received a copy of the GNU General Public License along

with this program. If not, see .



[cgit website]: https://git.zx2c4.com/cgit/

[gitweb website]: https://git-scm.com/docs/gitweb

[git-arr website]: https://blitiri.com.ar/p/git-arr/

[stagit website]: http://codemadness.nl/git/stagit/log.html

[libgit2 website]: https://libgit2.org/

[go website]: https://golang.org/

[discount website]: http://www.pell.portland.or.us/~orc/Code/discount/

[git2go repo]: https://github.com/libgit2/git2go

[git2go build]: https://github.com/libgit2/git2go#installing