README.md - stagit

1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
98 
99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
stagit
======

Personal fork of [stagit](https://git.codemadness.org/stagit/), a static git
page generator. It generates static HTML pages for a git repository.

This fork uses [md4c](https://github.com/mity/md4c) to convert the README
markdown into HTML and then shows it in an about page for each repository, this
adds a new dependency. On top of that, the assets have been changed, creating a
personal theme. The scripts have also been changed to fit my needs.


Features
--------

- Log of all commits from HEAD.
- Log and diffstat per commit.
- Show file tree with linkable line numbers.
- Show references: local branches and tags.
- Detect README and LICENSE file from HEAD and link it as a webpage.
- Detect submodules (.gitmodules file) from HEAD and link it as a webpage.
- Make index page for multiple repositories with stagit-index.
- After generating the pages (relatively slow) serving the files is very fast,
  simple and requires little resources (because the content is static), only a
  HTTP file server is required.
- Usable with text-browsers such as dillo, links, lynx and w3m.


Cons
----

- Not suitable for large repositories (2000+ commits), because diffstats are
  an expensive operation, the cache (-c flag) is a workaround for this in some
  cases.
- Not suitable for large repositories with many files, because all files are
  written for each execution of stagit. This is because stagit shows the lines
  of textfiles and there is no "cache" for file metadata (this would add more
  complexity to the code).
- Not suitable for repositories with many branches, a quite linear history is
  assumed (from HEAD).

  In these cases it is better to just use cgit or possibly change stagit to run
  as a CGI program.

- Relatively slow to run the first time (about 3 seconds for sbase, 1500+
  commits), incremental updates are faster.
- Does not support some of the dynamic features cgit has (this is by design,
  just use git locally), like:
  - Snapshot tarballs per commit.
  - File tree per commit.
  - History log of branches diverged from HEAD.
  - Stats (git shortlog -s).


Dependencies
------------

- C compiler (C99).
- libc (tested with OpenBSD, FreeBSD, NetBSD, Linux: glibc and musl).
- libgit2 (v0.22+).
- POSIX make (optional).
- [md4c](https://github.com/mity/md4c) (v0.4.4+).


Usage
-----

Make files per repository:

	$ mkdir -p htmlroot/htmlrepo1 && cd htmlroot/htmlrepo1
	$ stagit path/to/gitrepo1
	repeat for other repositories
	$ ...

Make index file for repositories:

	$ cd htmlroot
	$ stagit-index path/to/gitrepo1 \
	               path/to/gitrepo2 \
	               path/to/gitrepo3 > index.html


Build and install
-----------------

	$ make
	# make install


Documentation
-------------

See man pages: stagit(1) and stagit-index(1).


Building a static binary
------------------------

It may be useful to build static binaries, for example to run in a chroot.

It can be done like this at the time of writing (v0.24):

	cd libgit2-src

	# change the options in the CMake file: CMakeLists.txt
	BUILD_SHARED_LIBS to OFF (static)
	CURL to OFF              (not needed)
	USE_SSH OFF              (not needed)
	THREADSAFE OFF           (not needed)
	USE_OPENSSL OFF          (not needed, use builtin)

	mkdir -p build && cd build
	cmake ../
	make
	make install


Update files on git push
------------------------

Using a post-receive hook the static files can be automatically updated. Keep in
mind git push -f can change the history and the commits may need to be
recreated. This is because stagit checks if a commit file already exists. It
also has a cache (-c) option which can conflict with the new history. See
stagit(1).


Create .tar.gz archives by tag
------------------------------

	#!/bin/sh
	name="stagit"
	mkdir -p archives
	git tag -l | while read -r t; do
		f="archives/${name}-$(echo "${t}" | tr '/' '_').tar.gz"
		test -f "${f}" && continue
		git archive \
			--format tar.gz \
			--prefix "${t}/" \
			-o "${f}" \
			-- \
			"${t}"
	done