stagit

static git page generator
git clone git://git.2f30.org/stagit.git
Log | Files | Refs | README | LICENSE

README (3674B)


      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.
    153 - Not suitable for repositories with many branches, a quite linear history is
    154   assumed (from HEAD).
    155 - Relatively slow to run the first time (about 3 seconds for sbase,
    156   1500+ commits), incremental updates are faster.
    157 - Does not support some of the dynamic features cgit has, like:
    158   - snapshot tarballs.
    159   - file tree per commit.
    160   - history log of branches diverged from HEAD.
    161   - stats (git shortlog -s).
    162 
    163   this is by design, just use git locally.