README (5689B) - Raw
1 stagit 2 ------ 3 4 static git page generator. 5 6 Fork of stagit by Hiltjo Posthuma (https://codemadness.org/stagit.html). 7 This fork runs https://git.jakstys.lt/. 8 9 All output is content-addressed: pages that exist on disk are skipped, 10 making incremental runs fast (milliseconds/seconds). Initial generation of 11 large repos (50k+ commits) may take hours. 12 13 Usage 14 ----- 15 16 Make files per repository: 17 18 $ mkdir -p /srv/www/repo && cd /srv/www/repo 19 $ stagit /srv/git/repo.git 20 # or: stagit -C /srv/www/repo /srv/git/repo.git 21 22 Make index file for repositories: 23 24 $ cd /srv/www 25 $ stagit-index /srv/git/repo1.git /srv/git/repo2.git > index.html 26 # with org/ prefix: stagit-index -b /srv/git /srv/git/org/repo.git > index.html 27 28 Multiprocess blob/tree generation: 29 30 $ stagit -j 4 /srv/git/repo.git 31 32 33 Build and install 34 ----------------- 35 36 $ make 37 # make install 38 39 40 Dependencies 41 ------------ 42 43 - C compiler (C99). 44 - libc (tested with OpenBSD, FreeBSD, NetBSD, Linux: glibc and musl, macOS). 45 - libgit2 (v0.22+). 46 - libsqlite3. 47 - POSIX fork/waitpid. 48 - POSIX make (optional). 49 50 51 Documentation 52 ------------- 53 54 See man pages: stagit(1) and stagit-index(1). 55 56 57 Output structure 58 ---------------- 59 60 index.html README at HEAD (rendered), or empty navigation page 61 refs/ branches and tags, linking to commit log and tree pages 62 tags.xml Atom feed (tags) 63 commit/<id>/ diffstat and diff per commit 64 commits/<id>/ commit log page (content-addressed by tip) 65 commits/HEAD symlink -> commits/<headid>/ 66 commits/<refname> symlink -> commits/<tipid>/ for each branch/tag 67 blob/<oid>/ content-addressed blob (one per unique blob) 68 blob/<oid>/raw raw blob content (binary-safe download) 69 tree/<id>/ file listing at a specific commit, links to blob pages 70 tree/HEAD symlink -> tree/<headid>/ 71 tree/<refname> symlink -> tree/<tipid>/ for each branch/tag 72 latest/README symlink -> blob/<oid>/ for HEAD README 73 latest/LICENSE symlink -> blob/<oid>/ for HEAD LICENSE 74 stagit.db SQLite cache of commit stats 75 76 77 Building a static binary 78 ------------------------ 79 80 It may be useful to build static binaries, for example to run in a chroot. 81 82 It can be done like this at the time of writing (v0.24): 83 84 cd libgit2-src 85 86 # change the options in the CMake file: CMakeLists.txt 87 BUILD_SHARED_LIBS to OFF (static) 88 CURL to OFF (not needed) 89 USE_SSH OFF (not needed) 90 THREADSAFE OFF (not needed) 91 USE_OPENSSL OFF (not needed, use builtin) 92 93 mkdir -p build && cd build 94 cmake ../ 95 make 96 make install 97 98 99 Extract owner field from git config 100 ----------------------------------- 101 102 A way to extract the gitweb owner for example in the format: 103 104 [gitweb] 105 owner = Name here 106 107 Script: 108 109 #!/bin/sh 110 awk '/^[ ]*owner[ ]=/ { 111 sub(/^[^=]*=[ ]*/, ""); 112 print $0; 113 }' 114 115 116 Set clone URL for a directory of repos 117 -------------------------------------- 118 #!/bin/sh 119 cd "$dir" 120 for i in *; do 121 test -d "$i" && echo "git://git.codemadness.org/$i" > "$i/url" 122 done 123 124 125 Deployment with systemd 126 ------------------------ 127 128 post-receive hook appends repo name to a queue file. A systemd path unit 129 watches the queue and triggers regeneration. 130 131 post-receive hook (symlinked into each repo's hooks/): 132 133 #!/bin/sh 134 reponame="$(realpath --relative-to=/srv/git "$(pwd)")" 135 reponame="${reponame%.git}" 136 git update-server-info 137 printf '%s\n' "$reponame" >> /var/lib/stagit/dirty/queue 138 139 stagit-regen script: atomically moves queue to queue.work, deduplicates 140 repo names, runs stagit per repo, rebuilds per-org index with stagit-index, 141 copies style.css/favicon.png/logo.png into each 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 - Commit log per ref (branch/tag), content-addressed by tip commit. 189 - Diffstat and diff per commit. 190 - Content-addressed blob pages, deduplicated across all history. 191 - Tree page per commit, linked from refs and commit pages. 192 - Detect README and LICENSE from HEAD, link in navigation. 193 - Atom feed of tags (tags.xml). 194 - Multi-repository index page (stagit-index). 195 - Multiprocess blob and tree generation (-j flag). 196 - SQLite cache for commit stats (stagit.db), shared across refs. 197 - Atomic file writes (write .tmp, fsync, rename). 198 - Directory-style URLs (trailing slash, index.html inside directories). 199 - Ref symlinks: commits/<refname> and tree/<refname> point to tip. 200 - Stale symlink and tmpfile cleanup on each run. 201 - Purely static output; serve with any HTTP file server. 202 - Usable with text-browsers such as dillo, links, lynx and w3m. 203 204 This is a fork of stagit by Hiltjo Posthuma. The fork additions were mostly 205 generated by LLMs. 206 207 208 Cons 209 ---- 210 211 - Relatively slow to run the first time (about 3 seconds for sbase, 212 1500+ commits), though incremental updates are very fast. 213 - Does not support some of the dynamic features cgit has, like: 214 - Snapshot tarballs per commit. 215 - Stats (git shortlog -s). 216 217 This is by design, just use git locally.