stagit-gopher

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

README (3520B)


      1 stagit-gopher
      2 =============
      3 
      4 static git page generator for gopher.
      5 
      6 This generates pages in the geomyidae .gph file format:
      7 
      8 	http://git.r-36.net/geomyidae
      9 
     10 
     11 Usage
     12 -----
     13 
     14 Make files per repository:
     15 
     16 	$ mkdir -p gphdir && cd gphdir
     17 	$ stagit-gopher path-to-repo
     18 
     19 Make index file for repositories:
     20 
     21 	$ stagit-gopher-index repodir1 repodir2 repodir3 > index.gph
     22 
     23 
     24 Install
     25 -------
     26 
     27 $ make
     28 # make install
     29 
     30 
     31 Dependencies
     32 ------------
     33 
     34 - geomyidae (for .gph file serving).
     35 - libgit2 (v0.22+).
     36 - libc (tested with OpenBSD, FreeBSD, Linux: glibc and musl).
     37 - C compiler (C99).
     38 - make
     39 
     40 
     41 Documentation
     42 -------------
     43 
     44 See man pages: stagit-gopher(1) and stagit-gopher-index(1).
     45 
     46 
     47 Building a static binary
     48 ------------------------
     49 
     50 It may be useful to build static binaries, for example to run in a chroot.
     51 
     52 It can be done like this at the time of writing (v0.24):
     53 
     54 cd libgit2-src
     55 
     56 # change the options in the CMake file: CMakeLists.txt
     57 BUILD_SHARED_LIBS to OFF (static)
     58 CURL to OFF              (not needed)
     59 USE_SSH OFF              (not needed)
     60 THREADSAFE OFF           (not needed)
     61 USE_OPENSSL OFF          (not needed, use builtin)
     62 
     63 mkdir -p build && cd build
     64 cmake ../
     65 make
     66 make install
     67 
     68 
     69 Set clone url for a directory of repos
     70 --------------------------------------
     71 	#!/bin/sh
     72 	cd "$dir"
     73 	for i in *; do
     74 		test -d "$i" && echo "git://git.codemadness.org/$i" > "$i/url"
     75 	done
     76 
     77 
     78 Update files on git push
     79 ------------------------
     80 
     81 Using a post-receive hook the static files can be automatically updated.
     82 Keep in mind git push -f can change the history and the commits may need
     83 to be recreated. This is because stagit checks if a commit file already
     84 exists. It also has a cache (-c) option which can conflict with the new
     85 history. See stagit(1).
     86 
     87 git post-receive hook (repo/.git/hooks/post-receive):
     88 
     89 	#!/bin/sh
     90 	# detect git push -f
     91 	force=0
     92 	while read -r old new ref; do
     93 		hasrevs=$(git rev-list "$old" "^$new" | sed 1q)
     94 		if test -n "$hasrevs"; then
     95 			force=1
     96 			break
     97 		fi
     98 	done
     99 
    100 	# remove commits and .cache on git push -f
    101 	#if test "$force" = "1"; then
    102 	# ...
    103 	#fi
    104 
    105 	# see example_create.sh for normal creation of the files.
    106 
    107 
    108 Create .tar.gz archives by tag
    109 ------------------------------
    110 	#!/bin/sh
    111 	name="stagit"
    112 	mkdir -p archives
    113 	git tag -l | while read -r t; do
    114 		f="archives/$name-$t.tar.gz"
    115 		test -f "$f" || git archive --format tar.gz "$t" -o "$f"
    116 	done
    117 
    118 
    119 Features
    120 --------
    121 
    122 - Log of all commits from HEAD.
    123 - Log and diffstat per commit.
    124 - Show file tree with linkable line numbers.
    125 - Show references: local branches and tags.
    126 - Detect README and LICENSE file from HEAD and link it as a page.
    127 - Detect submodules (.gitmodules file) from HEAD and link it as a page.
    128 - Atom feed log (atom.xml).
    129 - Make index page for multiple repositories with stagit-gopher-index.
    130 - After generating the pages (relatively slow) serving the files is very fast,
    131   simple and requires little resources (because the content is static), only
    132   a geomyidae Gopher server is required.
    133 
    134 
    135 Cons
    136 ----
    137 
    138 - Not suitable for large repositories (2000+ commits), because diffstats are
    139   an expensive operation.
    140 - Not suitable for repositories with many branches, a quite linear history is
    141   assumed (from HEAD).
    142 - Relatively slow to run the first time (about 3 seconds for sbase,
    143   1500+ commits), incremental updates are faster.
    144 - Does not support some dynamic features like:
    145   - snapshot tarballs.
    146   - file tree per commit.
    147   - history log of branches diverged from HEAD.
    148   - stats (git shortlog -s).
    149 
    150   this is by design, just use git locally.