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