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