README

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