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