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