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, NetBSD, 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}-$(echo "${t}" | tr '/' '_').tar.gz"
 127                 test -f "${f}" && continue
 128                 git archive \
 129                         --format tar.gz \
 130                         --prefix "${t}/" \
 131                         -o "${f}" \
 132                         -- \
 133                         "${t}"
 134         done
 135
 136
 137 Features
 138 --------
 139
 140 - Log of all commits from HEAD.
 141 - Log and diffstat per commit.
 142 - Show file tree with linkable line numbers.
 143 - Show references: local branches and tags.
 144 - Detect README and LICENSE file from HEAD and link it as a webpage.
 145 - Detect submodules (.gitmodules file) from HEAD and link it as a webpage.
 146 - Atom feed log (atom.xml).
 147 - Make index page for multiple repositories with stagit-index.
 148 - After generating the pages (relatively slow) serving the files is very fast,
 149   simple and requires little resources (because the content is static), only
 150   a HTTP file server is required.
 151 - Usable with text-browsers such as dillo, links, lynx and w3m.
 152
 153
 154 Cons
 155 ----
 156
 157 - Not suitable for large repositories (2000+ commits), because diffstats are
 158   an expensive operation, the cache (-c flag) is a workaround for this in
 159   some cases.
 160 - Not suitable for large repositories with many files, because all files are
 161   written for each execution of stagit. This is because stagit shows the lines
 162   of textfiles and there is no "cache" for file metadata (this would add more
 163   complexity to the code).
 164 - Not suitable for repositories with many branches, a quite linear history is
 165   assumed (from HEAD).
 166
 167   In these cases it is better to just use cgit or possibly change stagit to
 168   run as a CGI program.
 169
 170 - Relatively slow to run the first time (about 3 seconds for sbase,
 171   1500+ commits), incremental updates are faster.
 172 - Does not support some of the dynamic features cgit has, like:
 173   - Snapshot tarballs per commit.
 174   - File tree per commit.
 175   - History log of branches diverged from HEAD.
 176   - Stats (git shortlog -s).
 177
 178   This is by design, just use git locally.