README

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