README

   1 stagit
   2 ------
   3
   4 static git page generator. personal fork with fast syntax highlighting via
   5 Chroma and some style and quality of life improvements.
   6
   7 It generates static HTML pages for a git repository.
   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
  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 - Chroma
  36 - cmark-gfm
  37 - POSIX make (optional).
  38
  39
  40 Documentation
  41 -------------
  42
  43 See man pages: stagit(1) and stagit-index(1).
  44
  45
  46 Building a static binary
  47 ------------------------
  48
  49 It may be useful to build static binaries, for example to run in a chroot.
  50
  51 It can be done like this at the time of writing (v0.24):
  52
  53 cd libgit2-src
  54
  55 # change the options in the CMake file: CMakeLists.txt
  56 BUILD_SHARED_LIBS to OFF (static)
  57 CURL to OFF              (not needed)
  58 USE_SSH OFF              (not needed)
  59 THREADSAFE OFF           (not needed)
  60 USE_OPENSSL OFF          (not needed, use builtin)
  61
  62 mkdir -p build && cd build
  63 cmake ../
  64 make
  65 make install
  66
  67
  68 Extract owner field from git config
  69 -----------------------------------
  70
  71 A way to extract the gitweb owner for example in the format:
  72
  73         [gitweb]
  74                 owner = Name here
  75
  76 Script:
  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         #!/bin/sh
  88         cd "$dir"
  89         for i in *; do
  90                 test -d "$i" && echo "git://git.codemadness.org/$i" > "$i/url"
  91         done
  92
  93
  94 Update files on git push
  95 ------------------------
  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         #!/bin/sh
 106         # detect git push -f
 107         force=0
 108         while read -r old new ref; do
 109                 hasrevs=$(git rev-list "$old" "^$new" | sed 1q)
 110                 if test -n "$hasrevs"; then
 111                         force=1
 112                         break
 113                 fi
 114         done
 115
 116         # remove commits and .cache on git push -f
 117         #if test "$force" = "1"; then
 118         # ...
 119         #fi
 120
 121         # see example_create.sh for normal creation of the files.
 122
 123
 124 Create .tar.gz archives by tag
 125 ------------------------------
 126         #!/bin/sh
 127         name="stagit"
 128         mkdir -p archives
 129         git tag -l | while read -r t; do
 130                 f="archives/${name}-$(echo "${t}" | tr '/' '_').tar.gz"
 131                 test -f "${f}" && continue
 132                 git archive \
 133                         --format tar.gz \
 134                         --prefix "${t}/" \
 135                         -o "${f}" \
 136                         -- \
 137                         "${t}"
 138         done
 139
 140
 141 Features
 142 --------
 143
 144 - Log of all commits from HEAD.
 145 - Log and diffstat per commit.
 146 - Show file tree with linkable line numbers.
 147 - Show references: local branches and tags.
 148 - Detect README and LICENSE file from HEAD and link it as a webpage.
 149 - Detect submodules (.gitmodules file) from HEAD and link it as a webpage.
 150 - Atom feed log (atom.xml).
 151 - Make index page for multiple repositories with stagit-index.
 152 - After generating the pages (relatively slow) serving the files is very fast,
 153   simple and requires little resources (because the content is static), only
 154   a HTTP file server is required.
 155 - Usable with text-browsers such as dillo, links, lynx and w3m.
 156
 157
 158 Cons
 159 ----
 160
 161 - Not suitable for large repositories (2000+ commits), because diffstats are
 162   an expensive operation, the cache (-c flag) is a workaround for this in
 163   some cases.
 164 - Not suitable for large repositories with many files, because all files are
 165   written for each execution of stagit. This is because stagit shows the lines
 166   of textfiles and there is no "cache" for file metadata (this would add more
 167   complexity to the code).
 168 - Not suitable for repositories with many branches, a quite linear history is
 169   assumed (from HEAD).
 170
 171   In these cases it is better to just use cgit or possibly change stagit to
 172   run as a CGI program.
 173
 174 - Relatively slow to run the first time (about 3 seconds for sbase,
 175   1500+ commits), incremental updates are faster.
 176 - Does not support some of the dynamic features cgit has, like:
 177   - Snapshot tarballs per commit.
 178   - File tree per commit.
 179   - History log of branches diverged from HEAD.
 180   - Stats (git shortlog -s).
 181
 182   This is by design, just use git locally.