README (raw) (5440B)
1 stagit 2 ------ 3 4 static git page generator. 5 6 It generates static HTML pages for a git repository. 7 8 9 gearsix changes 10 --------------- 11 12 Mostly just changes to the html templating. 13 14 stagit-index.c 15 16 - changed description value 17 - added the option for contain details 18 - changed favicon.png -> /logo.png 19 - changed style.css -> /style.css 20 - added #logo id to td displaying logo 21 - added "binary" (argv[0]) for error messages "$binary: ..." 22 - added optional "contact" row below description in table header 23 - split repo list into "original" and "forks", see "writebody()" 24 25 stagit.c 26 27 - added seperator between Refs | Atom 28 - added atom.xml feed link to menu 29 - changed favicon.png -> logo.png 30 - added rootpath ("/") 31 - logo.png & style.css paths are prepended with rootpath value 32 - added #logo id to td displaying logo 33 - added "forked from ..." in description (if repo is fork) 34 - added index.html for repo pages that redirect to ./log.html 35 36 misc 37 38 - changed logo size to 50x50 39 - moved style.css -> style-default.css 40 - added style-gearsix.css 41 42 43 Usage 44 ----- 45 46 Make files per repository: 47 48 $ mkdir -p htmlroot/htmlrepo1 && cd htmlroot/htmlrepo1 49 $ stagit path/to/gitrepo1 50 repeat for other repositories 51 $ ... 52 53 Make index file for repositories: 54 55 $ cd htmlroot 56 $ stagit-index path/to/gitrepo1 \ 57 path/to/gitrepo2 \ 58 path/to/gitrepo3 > index.html 59 60 61 Build and install 62 ----------------- 63 64 $ make 65 # make install 66 67 68 Dependencies 69 ------------ 70 71 - C compiler (C99). 72 - libc (tested with OpenBSD, FreeBSD, NetBSD, Linux: glibc and musl). 73 - libgit2 (v0.22+). 74 - POSIX make (optional). 75 76 77 Documentation 78 ------------- 79 80 See man pages: stagit(1) and stagit-index(1). 81 82 83 Building a static binary 84 ------------------------ 85 86 It may be useful to build static binaries, for example to run in a chroot. 87 88 It can be done like this at the time of writing (v0.24): 89 90 cd libgit2-src 91 92 # change the options in the CMake file: CMakeLists.txt 93 BUILD_SHARED_LIBS to OFF (static) 94 CURL to OFF (not needed) 95 USE_SSH OFF (not needed) 96 THREADSAFE OFF (not needed) 97 USE_OPENSSL OFF (not needed, use builtin) 98 99 mkdir -p build && cd build 100 cmake ../ 101 make 102 make install 103 104 105 Extract owner field from git config 106 ----------------------------------- 107 108 A way to extract the gitweb owner for example in the format: 109 110 [gitweb] 111 owner = Name here 112 113 Script: 114 115 #!/bin/sh 116 awk '/^[ ]*owner[ ]=/ { 117 sub(/^[^=]*=[ ]*/, ""); 118 print $0; 119 }' 120 121 122 Set clone URL for a directory of repos 123 -------------------------------------- 124 #!/bin/sh 125 cd "$dir" 126 for i in *; do 127 test -d "$i" && echo "git://git.codemadness.org/$i" > "$i/url" 128 done 129 130 131 Update files on git push 132 ------------------------ 133 134 Using a post-receive hook the static files can be automatically updated. 135 Keep in mind git push -f can change the history and the commits may need 136 to be recreated. This is because stagit checks if a commit file already 137 exists. It also has a cache (-c) option which can conflict with the new 138 history. See stagit(1). 139 140 git post-receive hook (repo/.git/hooks/post-receive): 141 142 #!/bin/sh 143 # detect git push -f 144 force=0 145 while read -r old new ref; do 146 hasrevs=$(git rev-list "$old" "^$new" | sed 1q) 147 if test -n "$hasrevs"; then 148 force=1 149 break 150 fi 151 done 152 153 # remove commits and .cache on git push -f 154 #if test "$force" = "1"; then 155 # ... 156 #fi 157 158 # see example_create.sh for normal creation of the files. 159 160 161 Create .tar.gz archives by tag 162 ------------------------------ 163 #!/bin/sh 164 name="stagit" 165 mkdir -p archives 166 git tag -l | while read -r t; do 167 f="archives/${name}-$(echo "${t}" | tr '/' '_').tar.gz" 168 test -f "${f}" && continue 169 git archive \ 170 --format tar.gz \ 171 --prefix "${t}/" \ 172 -o "${f}" \ 173 -- \ 174 "${t}" 175 done 176 177 178 Features 179 -------- 180 181 - Log of all commits from HEAD. 182 - Log and diffstat per commit. 183 - Show file tree with linkable line numbers. 184 - Show references: local branches and tags. 185 - Detect README and LICENSE file from HEAD and link it as a webpage. 186 - Detect submodules (.gitmodules file) from HEAD and link it as a webpage. 187 - Atom feed of the commit log (atom.xml). 188 - Atom feed of the tags/refs (tags.xml). 189 - Make index page for multiple repositories with stagit-index. 190 - After generating the pages (relatively slow) serving the files is very fast, 191 simple and requires little resources (because the content is static), only 192 a HTTP file server is required. 193 - Usable with text-browsers such as dillo, links, lynx and w3m. 194 195 196 Cons 197 ---- 198 199 - Not suitable for large repositories (2000+ commits), because diffstats are 200 an expensive operation, the cache (-c flag) is a workaround for this in 201 some cases. 202 - Not suitable for large repositories with many files, because all files are 203 written for each execution of stagit. This is because stagit shows the lines 204 of textfiles and there is no "cache" for file metadata (this would add more 205 complexity to the code). 206 - Not suitable for repositories with many branches, a quite linear history is 207 assumed (from HEAD). 208 209 In these cases it is better to just use cgit or possibly change stagit to 210 run as a CGI program. 211 212 - Relatively slow to run the first time (about 3 seconds for sbase, 213 1500+ commits), incremental updates are faster. 214 - Does not support some of the dynamic features cgit has, like: 215 - Snapshot tarballs per commit. 216 - File tree per commit. 217 - History log of branches diverged from HEAD. 218 - Stats (git shortlog -s). 219 220 This is by design, just use git locally.