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