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