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