README - stagit-gopher - A git gopher frontend. (mirror)
(HTM) git clone git://bitreich.org/stagit-gopher/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/stagit-gopher/
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Tags
(DIR) README
(DIR) 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 chroot.
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" > "$i/url"
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 fast,
143 simple and requires little resources (because the content is static), only
144 a geomyidae Gopher server is required.
145
146
147 Cons
148 ----
149
150 - Not suitable for large repositories (2000+ commits), because diffstats are
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 are
154 written for each execution of stagit. This is because stagit shows the lines
155 of textfiles and there is no "cache" for file metadata (this would add more
156 complexity to the code).
157 - Not suitable for repositories with many branches, a quite linear history is
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.