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