README - stagit - static git page generator
(HTM) git clone git://git.codemadness.org/stagit
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
README (4494B)
---
1 stagit
2 ------
3
4 static git page generator.
5
6 It generates static HTML pages for a git repository.
7
8
9 Usage
10 -----
11
12 Make files per repository:
13
14 $ mkdir -p htmlroot/htmlrepo1 && cd htmlroot/htmlrepo1
15 $ stagit path/to/gitrepo1
16 repeat for other repositories
17 $ ...
18
19 Make 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
27 Build and install
28 -----------------
29
30 $ make
31 # make install
32
33
34 Dependencies
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
43 Documentation
44 -------------
45
46 See man pages: stagit(1) and stagit-index(1).
47
48
49 Building a static binary
50 ------------------------
51
52 It may be useful to build static binaries, for example to run in a chroot.
53
54 It can be done like this at the time of writing (v0.24):
55
56 cd libgit2-src
57
58 # change the options in the CMake file: CMakeLists.txt
59 BUILD_SHARED_LIBS to OFF (static)
60 CURL to OFF (not needed)
61 USE_SSH OFF (not needed)
62 THREADSAFE OFF (not needed)
63 USE_OPENSSL OFF (not needed, use builtin)
64
65 mkdir -p build && cd build
66 cmake ../
67 make
68 make install
69
70
71 Extract owner field from git config
72 -----------------------------------
73
74 A way to extract the gitweb owner for example in the format:
75
76 [gitweb]
77 owner = Name here
78
79 Script:
80
81 #!/bin/sh
82 awk '/^[ ]*owner[ ]=/ {
83 sub(/^[^=]*=[ ]*/, "");
84 print $0;
85 }'
86
87
88 Set 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
97 Update files on git push
98 ------------------------
99
100 Using a post-receive hook the static files can be automatically updated.
101 Keep in mind git push -f can change the history and the commits may need
102 to be recreated. This is because stagit checks if a commit file already
103 exists. It also has a cache (-c) option which can conflict with the new
104 history. See stagit(1).
105
106 git 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
127 Create .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
144 Features
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
162 Cons
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.