README
1stagit
2------
3
4static git page generator.
5
6It generates static HTML pages for a git repository.
7
8
9Usage
10-----
11
12Make files per repository:
13
14 $ mkdir -p htmlroot/htmlrepo1 && cd htmlroot/htmlrepo1
15 $ stagit path/to/gitrepo1
16 repeat for other repositories
17 $ ...
18
19Make index file for repositories:
20
21 $ cd htmlroot
22 $ stagit-index path/to/gitrepo1 \
23 path/to/gitrepo2 \
24 path/to/gitrepo3 > index.html
25
26
27Build and install
28-----------------
29
30$ make
31# make install
32
33
34Dependencies
35------------
36
37- C compiler (C99).
38- libc (tested with OpenBSD, FreeBSD, NetBSD, Linux: glibc and musl).
39- libgit2 (v0.22+).
40- POSIX make (optional).
41
42
43Documentation
44-------------
45
46See man pages: stagit(1) and stagit-index(1).
47
48
49Building a static binary
50------------------------
51
52It may be useful to build static binaries, for example to run in a chroot.
53
54It can be done like this at the time of writing (v0.24):
55
56cd libgit2-src
57
58# change the options in the CMake file: CMakeLists.txt
59BUILD_SHARED_LIBS to OFF (static)
60CURL to OFF (not needed)
61USE_SSH OFF (not needed)
62THREADSAFE OFF (not needed)
63USE_OPENSSL OFF (not needed, use builtin)
64
65mkdir -p build && cd build
66cmake ../
67make
68make install
69
70
71Extract owner field from git config
72-----------------------------------
73
74A way to extract the gitweb owner for example in the format:
75
76 [gitweb]
77 owner = Name here
78
79Script:
80
81 #!/bin/sh
82 awk '/^[ ]*owner[ ]=/ {
83 sub(/^[^=]*=[ ]*/, "");
84 print $0;
85 }'
86
87
88Set clone URL for a directory of repos
89--------------------------------------
90 #!/bin/sh
91 cd "$dir"
92 for i in *; do
93 test -d "$i" && echo "git://git.codemadness.org/$i" > "$i/url"
94 done
95
96
97Update files on git push
98------------------------
99
100Using a post-receive hook the static files can be automatically updated.
101Keep in mind git push -f can change the history and the commits may need
102to be recreated. This is because stagit checks if a commit file already
103exists. It also has a cache (-c) option which can conflict with the new
104history. See stagit(1).
105
106git post-receive hook (repo/.git/hooks/post-receive):
107
108 #!/bin/sh
109 # detect git push -f
110 force=0
111 while read -r old new ref; do
112 hasrevs=$(git rev-list "$old" "^$new" | sed 1q)
113 if test -n "$hasrevs"; then
114 force=1
115 break
116 fi
117 done
118
119 # remove commits and .cache on git push -f
120 #if test "$force" = "1"; then
121 # ...
122 #fi
123
124 # see example_create.sh for normal creation of the files.
125
126
127Create .tar.gz archives by tag
128------------------------------
129 #!/bin/sh
130 name="stagit"
131 mkdir -p archives
132 git tag -l | while read -r t; do
133 f="archives/${name}-$(echo "${t}" | tr '/' '_').tar.gz"
134 test -f "${f}" && continue
135 git archive \
136 --format tar.gz \
137 --prefix "${t}/" \
138 -o "${f}" \
139 -- \
140 "${t}"
141 done
142
143
144Features
145--------
146
147- Log of all commits from HEAD.
148- Log and diffstat per commit.
149- Show file tree with linkable line numbers.
150- Show references: local branches and tags.
151- Detect README and LICENSE file from HEAD and link it as a webpage.
152- Detect submodules (.gitmodules file) from HEAD and link it as a webpage.
153- Atom feed of the commit log (atom.xml).
154- Atom feed of the tags/refs (tags.xml).
155- Make index page for multiple repositories with stagit-index.
156- After generating the pages (relatively slow) serving the files is very fast,
157 simple and requires little resources (because the content is static), only
158 a HTTP file server is required.
159- Usable with text-browsers such as dillo, links, lynx and w3m.
160
161
162Cons
163----
164
165- Not suitable for large repositories (2000+ commits), because diffstats are
166 an expensive operation, the cache (-c flag) is a workaround for this in
167 some cases.
168- Not suitable for large repositories with many files, because all files are
169 written for each execution of stagit. This is because stagit shows the lines
170 of textfiles and there is no "cache" for file metadata (this would add more
171 complexity to the code).
172- Not suitable for repositories with many branches, a quite linear history is
173 assumed (from HEAD).
174
175 In these cases it is better to just use cgit or possibly change stagit to
176 run as a CGI program.
177
178- Relatively slow to run the first time (about 3 seconds for sbase,
179 1500+ commits), incremental updates are faster.
180- Does not support some of the dynamic features cgit has, like:
181 - Snapshot tarballs per commit.
182 - File tree per commit.
183 - History log of branches diverged from HEAD.
184 - Stats (git shortlog -s).
185
186 This is by design, just use git locally.
187