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