tREADME - stagit - [fork] customized build of stagit, the static git page gener… | |
git clone git://src.adamsgaard.dk/stagit | |
Log | |
Files | |
Refs | |
README | |
LICENSE | |
--- | |
tREADME (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 chroo… | |
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" > "$… | |
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 webpag… | |
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… | |
157 simple and requires little resources (because the content is static), … | |
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… | |
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… | |
169 written for each execution of stagit. This is because stagit shows the… | |
170 of textfiles and there is no "cache" for file metadata (this would add… | |
171 complexity to the code). | |
172 - Not suitable for repositories with many branches, a quite linear histo… | |
173 assumed (from HEAD). | |
174 | |
175 In these cases it is better to just use cgit or possibly change stagit… | |
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. |