stagit

My personal build of stagit
README.md (4333B)

  1 # stagit
  2 
  3 static git page generator.
  4 
  5 It generates static HTML pages for a git repository.
  6 
  7 
  8 ## Usage
  9 
 10 Make files per repository:
 11 
 12 ```
 13 $ mkdir -p htmldir && cd htmldir
 14 $ stagit path-to-repo
 15 ```
 16 
 17 Make index file for repositories:
 18 
 19 ```
 20 $ stagit-index repodir1 repodir2 repodir3 > index.html
 21 ```
 22 
 23 
 24 ## Build and install
 25 
 26 ```
 27 $ make
 28 # make install
 29 ```
 30 
 31 
 32 ## Dependencies
 33 
 34 * C compiler (C99).
 35 * libc (tested with OpenBSD, FreeBSD, NetBSD, Linux: glibc and musl).
 36 * libgit2 (v0.22+).
 37 * [cmark](https://github.com/commonmark/cmark).
 38 * POSIX make (optional).
 39 
 40 ## Documentation
 41 
 42 See man pages: stagit(1) and stagit-index(1).
 43 
 44 ## Building a static binary
 45 
 46 It may be useful to build static binaries, for example to run in a chroot.
 47 
 48 It can be done like this at the time of writing (v0.24):
 49 
 50 ```
 51 cd libgit2-src
 52 
 53 # change the options in the CMake file: CMakeLists.txt
 54 BUILD_SHARED_LIBS to OFF (static)
 55 CURL to OFF              (not needed)
 56 USE_SSH OFF              (not needed)
 57 THREADSAFE OFF           (not needed)
 58 USE_OPENSSL OFF          (not needed, use builtin)
 59 
 60 mkdir -p build && cd build
 61 cmake ../
 62 make
 63 make install
 64 ```
 65 
 66 ## Extract owner field from git config
 67 
 68 A way to extract the gitweb owner for example in the format:
 69 
 70 ```
 71 [gitweb]
 72 owner = Name here
 73 ```
 74 
 75 Script:
 76 
 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 ```
 88 #!/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 ```
 94 
 95 ## Update files on git push
 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 ```
106 #!/bin/sh
107 # detect git push -f
108 force=0
109 while read -r old new ref; do
110   hasrevs=$(git rev-list "$old" "^$new" | sed 1q)
111   if test -n "$hasrevs"; then
112     force=1
113     break
114   fi
115 done
116 
117 # remove commits and .cache on git push -f
118 #if test "$force" = "1"; then
119 # ...
120 #fi
121 
122 # see example_create.sh for normal creation of the files.
123 ```
124 
125 ## Create .tar.gz archives by tag
126 
127 ```
128 #!/bin/sh
129 name="stagit"
130 mkdir -p archives
131 git tag -l | while read -r t; do
132   f="archives/${name}-$(echo "${t}" | tr '/' '_').tar.gz"
133   test -f "${f}" && continue
134   git archive \
135     --format tar.gz \
136     --prefix "${t}/" \
137     -o "${f}" \
138     -- \
139     "${t}"
140 done
141 ```
142 
143 
144 ## Features
145 
146 * Log of all commits from HEAD.
147 * Log and diffstat per commit.
148 * Show file tree with linkable line numbers.
149 * Show references: local branches and tags.
150 * Detect README and LICENSE file from HEAD and link it as a webpage.
151 * Render [Markdown](https://commonmark.org/) READMEs as fancy looking HTML.
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 * Not suitable for large repositories (2000+ commits), because diffstats are
165   an expensive operation, the cache (*c flag) is a workaround for this in
166   some cases.
167 * Not suitable for large repositories with many files, because all files are
168   written for each execution of stagit. This is because stagit shows the lines
169   of textfiles and there is no "cache" for file metadata (this would add more
170   complexity to the code).
171 * Not suitable for repositories with many branches, a quite linear history is
172   assumed (from HEAD).
173 
174   In these cases it is better to just use cgit or possibly change stagit to
175   run as a CGI program.
176 
177 * Relatively slow to run the first time (about 3 seconds for sbase,
178   1500+ commits), incremental updates are faster.
179 * Does not support some of the dynamic features cgit has, like:
180   * Snapshot tarballs per commit.
181   * File tree per commit.
182   * History log of branches diverged from HEAD.
183   * Stats (git shortlog -s).
184 
185   This is by design, just use git locally.