stagit

static git page - forked from git.codemadness.org/stagit
git clone git://src.gearsix.net/stagitstagit.zip
Log | Files | Refs | Atom | README | LICENSE

README (raw) (5571B)


   1 stagit
   2 ------
   3 
   4 static git page generator.
   5 
   6 It generates static HTML pages for a git repository.
   7 
   8 
   9 gearsix changes
  10 ---------------
  11 
  12 Mostly just changes to the html templating.
  13 
  14 stagit-index.c
  15 
  16 	- changed description value
  17 	- added the option for contain details
  18 	- changed favicon.png -> /logo.png
  19 	- changed style.css -> /style.css
  20 	- added #logo id to td displaying logo
  21 	- added "binary" (argv[0]) for error messages "$binary: ..."
  22 	- added optional "contact" row below description in table header
  23 	- split repo list into "original" and "forks", see "writebody()"
  24 
  25 stagit.c
  26 
  27 	- added the build option to zip repos (for download), requires `-DZIP`
  28 	- added seperator between Refs | Atom
  29 	- added atom.xml feed link to menu
  30 	- changed favicon.png -> logo.png
  31 	- added rootpath ("/")
  32 	- logo.png & style.css paths are prepended with rootpath value
  33 	- added #logo id to td displaying logo
  34 	- added "forked from ..." in description (if repo is fork)
  35 	- added index.html for repo pages that redirect to ./log.html
  36 	- numbered file lines have 4 spaces padding instead of 7.
  37 
  38 misc
  39 
  40 	- changed logo size to 50x50
  41 	- moved style.css -> style-default.css
  42 	- added style-gearsix.css
  43 
  44 
  45 Usage
  46 -----
  47 
  48 Make files per repository:
  49 
  50 	$ mkdir -p htmlroot/htmlrepo1 && cd htmlroot/htmlrepo1
  51 	$ stagit path/to/gitrepo1
  52 	repeat for other repositories
  53 	$ ...
  54 
  55 Make index file for repositories:
  56 
  57 	$ cd htmlroot
  58 	$ stagit-index path/to/gitrepo1 \
  59 	               path/to/gitrepo2 \
  60 	               path/to/gitrepo3 > index.html
  61 
  62 
  63 Build and install
  64 -----------------
  65 
  66 $ make
  67 # make install
  68 
  69 
  70 Dependencies
  71 ------------
  72 
  73 - C compiler (C99).
  74 - libc (tested with OpenBSD, FreeBSD, NetBSD, Linux: glibc and musl).
  75 - libgit2 (v0.22+).
  76 - POSIX make (optional).
  77 
  78 
  79 Documentation
  80 -------------
  81 
  82 See man pages: stagit(1) and stagit-index(1).
  83 
  84 
  85 Building a static binary
  86 ------------------------
  87 
  88 It may be useful to build static binaries, for example to run in a chroot.
  89 
  90 It can be done like this at the time of writing (v0.24):
  91 
  92 cd libgit2-src
  93 
  94 # change the options in the CMake file: CMakeLists.txt
  95 BUILD_SHARED_LIBS to OFF (static)
  96 CURL to OFF              (not needed)
  97 USE_SSH OFF              (not needed)
  98 THREADSAFE OFF           (not needed)
  99 USE_OPENSSL OFF          (not needed, use builtin)
 100 
 101 mkdir -p build && cd build
 102 cmake ../
 103 make
 104 make install
 105 
 106 
 107 Extract owner field from git config
 108 -----------------------------------
 109 
 110 A way to extract the gitweb owner for example in the format:
 111 
 112 	[gitweb]
 113 		owner = Name here
 114 
 115 Script:
 116 
 117 	#!/bin/sh
 118 	awk '/^[ 	]*owner[ 	]=/ {
 119 		sub(/^[^=]*=[ 	]*/, "");
 120 		print $0;
 121 	}'
 122 
 123 
 124 Set clone URL for a directory of repos
 125 --------------------------------------
 126 	#!/bin/sh
 127 	cd "$dir"
 128 	for i in *; do
 129 		test -d "$i" && echo "git://git.codemadness.org/$i" > "$i/url"
 130 	done
 131 
 132 
 133 Update files on git push
 134 ------------------------
 135 
 136 Using a post-receive hook the static files can be automatically updated.
 137 Keep in mind git push -f can change the history and the commits may need
 138 to be recreated. This is because stagit checks if a commit file already
 139 exists. It also has a cache (-c) option which can conflict with the new
 140 history. See stagit(1).
 141 
 142 git post-receive hook (repo/.git/hooks/post-receive):
 143 
 144 	#!/bin/sh
 145 	# detect git push -f
 146 	force=0
 147 	while read -r old new ref; do
 148 		hasrevs=$(git rev-list "$old" "^$new" | sed 1q)
 149 		if test -n "$hasrevs"; then
 150 			force=1
 151 			break
 152 		fi
 153 	done
 154 
 155 	# remove commits and .cache on git push -f
 156 	#if test "$force" = "1"; then
 157 	# ...
 158 	#fi
 159 
 160 	# see example_create.sh for normal creation of the files.
 161 
 162 
 163 Create .tar.gz archives by tag
 164 ------------------------------
 165 	#!/bin/sh
 166 	name="stagit"
 167 	mkdir -p archives
 168 	git tag -l | while read -r t; do
 169 		f="archives/${name}-$(echo "${t}" | tr '/' '_').tar.gz"
 170 		test -f "${f}" && continue
 171 		git archive \
 172 			--format tar.gz \
 173 			--prefix "${t}/" \
 174 			-o "${f}" \
 175 			-- \
 176 			"${t}"
 177 	done
 178 
 179 
 180 Features
 181 --------
 182 
 183 - Log of all commits from HEAD.
 184 - Log and diffstat per commit.
 185 - Show file tree with linkable line numbers.
 186 - Show references: local branches and tags.
 187 - Detect README and LICENSE file from HEAD and link it as a webpage.
 188 - Detect submodules (.gitmodules file) from HEAD and link it as a webpage.
 189 - Atom feed of the commit log (atom.xml).
 190 - Atom feed of the tags/refs (tags.xml).
 191 - Make index page for multiple repositories with stagit-index.
 192 - After generating the pages (relatively slow) serving the files is very fast,
 193   simple and requires little resources (because the content is static), only
 194   a HTTP file server is required.
 195 - Usable with text-browsers such as dillo, links, lynx and w3m.
 196 
 197 
 198 Cons
 199 ----
 200 
 201 - Not suitable for large repositories (2000+ commits), because diffstats are
 202   an expensive operation, the cache (-c flag) is a workaround for this in
 203   some cases.
 204 - Not suitable for large repositories with many files, because all files are
 205   written for each execution of stagit. This is because stagit shows the lines
 206   of textfiles and there is no "cache" for file metadata (this would add more
 207   complexity to the code).
 208 - Not suitable for repositories with many branches, a quite linear history is
 209   assumed (from HEAD).
 210 
 211   In these cases it is better to just use cgit or possibly change stagit to
 212   run as a CGI program.
 213 
 214 - Relatively slow to run the first time (about 3 seconds for sbase,
 215   1500+ commits), incremental updates are faster.
 216 - Does not support some of the dynamic features cgit has, like:
 217   - Snapshot tarballs per commit.
 218   - File tree per commit.
 219   - History log of branches diverged from HEAD.
 220   - Stats (git shortlog -s).
 221 
 222   This is by design, just use git locally.