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