README (6169B) - Raw
1 stagit 2 ------ 3 4 static git page generator. 5 6 It generates static HTML pages for a git repository. 7 8 This is a fork of stagit by Hiltjo Posthuma 9 (https://codemadness.org/stagit.html) with additional features / fixes 10 documented below. This fork powers https://git.jakstys.lt/ 11 12 13 Usage 14 ----- 15 16 Make files per repository: 17 18 $ mkdir -p htmlroot/htmlrepo1 && cd htmlroot/htmlrepo1 19 $ stagit path/to/gitrepo1 20 repeat for other repositories 21 $ ... 22 23 Make index file for repositories: 24 25 $ cd htmlroot 26 $ stagit-index path/to/gitrepo1 \ 27 path/to/gitrepo2 \ 28 path/to/gitrepo3 > index.html 29 30 Multithreaded blob/tree generation: 31 32 $ stagit -T0 path/to/repo # auto-detect CPU count 33 $ stagit -T4 path/to/repo # 4 threads 34 35 36 Build and install 37 ----------------- 38 39 $ make 40 # make install 41 42 43 Dependencies 44 ------------ 45 46 - C compiler (C99). 47 - libc (tested with OpenBSD, FreeBSD, NetBSD, Linux: glibc and musl, macOS). 48 - libgit2 (v0.22+). 49 - pthreads. 50 - POSIX make (optional). 51 52 53 Documentation 54 ------------- 55 56 See man pages: stagit(1) and stagit-index(1). 57 58 59 Output structure 60 ---------------- 61 62 log.html commit log 63 files.html file listing at HEAD 64 refs.html branches and tags, each linking to its tree page 65 index.html README content, or redirect to log.html 66 atom.xml Atom feed (commits) 67 tags.xml Atom feed (tags) 68 commit/<id>/ diffstat and diff per commit 69 file/<path>/ file content at HEAD with line numbers 70 raw/<path> raw file content at HEAD 71 blob/<oid>/ content-addressed blob (one per unique blob across history) 72 tree/<commitid>/ file listing at a specific commit, links to blob pages 73 tree/<refname> -> symlink to tree/<commitid> for each branch/tag 74 75 76 Building a static binary 77 ------------------------ 78 79 It may be useful to build static binaries, for example to run in a chroot. 80 81 It can be done like this at the time of writing (v0.24): 82 83 cd libgit2-src 84 85 # change the options in the CMake file: CMakeLists.txt 86 BUILD_SHARED_LIBS to OFF (static) 87 CURL to OFF (not needed) 88 USE_SSH OFF (not needed) 89 THREADSAFE OFF (not needed) 90 USE_OPENSSL OFF (not needed, use builtin) 91 92 mkdir -p build && cd build 93 cmake ../ 94 make 95 make install 96 97 98 Extract owner field from git config 99 ----------------------------------- 100 101 A way to extract the gitweb owner for example in the format: 102 103 [gitweb] 104 owner = Name here 105 106 Script: 107 108 #!/bin/sh 109 awk '/^[ ]*owner[ ]=/ { 110 sub(/^[^=]*=[ ]*/, ""); 111 print $0; 112 }' 113 114 115 Set clone URL for a directory of repos 116 -------------------------------------- 117 #!/bin/sh 118 cd "$dir" 119 for i in *; do 120 test -d "$i" && echo "git://git.codemadness.org/$i" > "$i/url" 121 done 122 123 124 Deployment with systemd 125 ------------------------ 126 127 post-receive hook appends repo name to a queue file. A systemd path unit 128 watches the queue and triggers regeneration. 129 130 post-receive hook (symlinked into each repo's hooks/): 131 132 #!/bin/sh 133 reponame="$(realpath --relative-to=/srv/git "$(pwd)")" 134 reponame="${reponame%.git}" 135 git update-server-info 136 printf '%s\n' "$reponame" >> /var/lib/stagit/dirty/queue 137 138 stagit-regen script: atomically moves queue to queue.work, deduplicates 139 repo names, runs stagit -c <cachefile> -T0 per repo, rebuilds per-org 140 index with stagit-index, copies style.css/favicon.png/logo.png into each 141 output dir. 142 143 systemd units: 144 145 # stagit-regen.service 146 [Unit] 147 Description=Regenerate stagit HTML pages 148 149 [Service] 150 Type=oneshot 151 User=git 152 Group=git 153 ExecStart=/usr/local/bin/stagit-regen 154 155 # stagit-regen.path 156 [Unit] 157 Description=Watch for stagit regeneration triggers 158 159 [Path] 160 PathExists=/var/lib/stagit/dirty/queue 161 162 [Install] 163 WantedBy=multi-user.target 164 165 Concurrent pushes during regeneration are picked up on the next trigger. 166 167 168 Create .tar.gz archives by tag 169 ------------------------------ 170 #!/bin/sh 171 name="stagit" 172 mkdir -p archives 173 git tag -l | while read -r t; do 174 f="archives/${name}-$(echo "${t}" | tr '/' '_').tar.gz" 175 test -f "${f}" && continue 176 git archive \ 177 --format tar.gz \ 178 --prefix "${t}/" \ 179 -o "${f}" \ 180 -- \ 181 "${t}" 182 done 183 184 185 Features 186 -------- 187 188 - Log of all commits from HEAD. 189 - Log and diffstat per commit. 190 - Show file tree with linkable line numbers. 191 - Show references: local branches and tags. 192 - Detect README and LICENSE file from HEAD and link it as a webpage. 193 - Detect submodules (.gitmodules file) from HEAD and link it as a webpage. 194 - Atom feed of the commit log (atom.xml). 195 - Atom feed of the tags/refs (tags.xml). 196 - Make index page for multiple repositories with stagit-index. 197 - After generating the pages (relatively slow) serving the files is very fast, 198 simple and requires little resources (because the content is static), only 199 a HTTP file server is required. 200 - Usable with text-browsers such as dillo, links, lynx and w3m. 201 202 Fork additions 203 .............. 204 205 - Multithreaded blob and tree generation (-T flag, -T0 for auto-detect). 206 - Content-addressed blob pages (blob/<oid>/), deduplicated across commits. 207 - Tree page per commit (tree/<commitid>/), linked from refs and commit pages. 208 - Raw file output (raw/<filepath>). 209 - index.html renders README if present, otherwise redirects to log.html. 210 - Atomic file writes (write to .tmp, fsync, rename). 211 - Directory-style URLs (trailing slash, index.html inside directories). 212 - Tree aliases: symlinks from tree/<refname> to tree/<commitid>. 213 - Refs link to their tree pages. 214 215 The fork additions were mostly generated using LLMs. 216 217 218 Cons 219 ---- 220 221 - Not suitable for large repositories (2000+ commits), because diffstats are 222 an expensive operation, the cache (-c flag) is a workaround for this in 223 some cases. 224 - Not suitable for repositories with many branches, a quite linear history is 225 assumed (from HEAD). 226 227 In these cases it is better to just use cgit or possibly change stagit to 228 run as a CGI program. 229 230 - Relatively slow to run the first time (about 3 seconds for sbase, 231 1500+ commits), incremental updates are faster. 232 - Does not support some of the dynamic features cgit has, like: 233 - Snapshot tarballs per commit. 234 - History log of branches diverged from HEAD. 235 - Stats (git shortlog -s). 236 237 This is by design, just use git locally.