stagit

commit

1b449f3247c34ba8790e126bafc41c8a921a7be8

parent

974fc29f55cfd28355316ada921ed2ce22056721

Author

Tobias Bengfort <tobias.bengfort@posteo.de>

Date

2020-03-29 19:04

rewrite README

Diffstat

3 files changed, 101 insertions, 182 deletions

diff --git a/LICENSE b/LICENSE

@@ -1,5 +1,6 @@
    1     1 MIT/X Consortium License
    2     2 
   -1     3 (c) 2020      Tobias Bengfort <tobias.bengfort@posteo.de>
    3     4 (c) 2015-2019 Hiltjo Posthuma <hiltjo@codemadness.org>
    4     5 (c) 2015-2016 Dimitris Papastamos <sin@2f30.org>
    5     6 

diff --git a/README b/README

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

diff --git a/README.md b/README.md

@@ -0,0 +1,100 @@
   -1     1 # stagit
   -1     2 
   -1     3 This is my personal fork of [stagit](https://git.codemadness.org/stagit/)
   -1     4 combined with access control scripts inspired by
   -1     5 [gitolite](https://gitolite.com/gitolite/). Together they are a simple yet
   -1     6 powerful solution for hosting git repositories.
   -1     7 
   -1     8 -	All (git-)users use the same (ssh-)user.
   -1     9 -	Access to repos is controlled using two scripts:
   -1    10 	-	one is called via the `command` option in `~/.ssh/authorized_keys`
   -1    11 	-	the second one is called via the `update` git hook
   -1    12 -	A third script is called via the `post-update` git hook. If a public
   -1    13 	repository was created/updated, a corresponding static website is
   -1    14 	created/updated automatically.
   -1    15 
   -1    16 ## Installation and setup
   -1    17 
   -1    18 ```
   -1    19 $ make
   -1    20 $ make install
   -1    21 ```
   -1    22 
   -1    23 Then setup access control:
   -1    24 
   -1    25 -	Create a user `git`
   -1    26 -	As that user, create the files `~/stagit.conf` and `~/.ssh/authorized_keys`
   -1    27 	(see next sections).
   -1    28 -	Whenever you change the config, run `python3 -m stagit` to apply the
   -1    29 	changes, e.g. create repositories. (Note that this will never delete a
   -1    30 	repository to prevent data loss.)
   -1    31 
   -1    32 ## stagit.conf
   -1    33 
   -1    34 The conf file is inspired by the [corresponding file in
   -1    35 gitolite](https://gitolite.com/gitolite/conf.html), but has a more INI-like
   -1    36 structure.
   -1    37 
   -1    38 ```
   -1    39 [GROUPS]
   -1    40 @staff = dilbert alice
   -1    41 
   -1    42 [private]
   -1    43 !RW+ = admin
   -1    44 
   -1    45 [example]
   -1    46 desc = my shiny new project
   -1    47 !RW+ = @staff
   -1    48 !R   = @all @public
   -1    49 ```
   -1    50 
   -1    51 Every section defines one repo, except for the special `GROUPS` section which
   -1    52 can be used to define groups of users. Groups are prefixed with a `@`. Access
   -1    53 permissions are prefixed with a `!`. `RW+` controls read, write, and full
   -1    54 access. Full access includes force-pushing and creating tags.
   -1    55 
   -1    56 There are two special groups: `@all` matches all users. `@public` enables
   -1    57 anonymous access via website and
   -1    58 [git-daemon](https://git-scm.com/book/en/v2/Git-on-the-Server-Git-Daemon).
   -1    59 
   -1    60 ## Authorized keys
   -1    61 
   -1    62 The authorized keys file should look roughly like this:
   -1    63 
   -1    64 ```
   -1    65 command="/usr/lib/stagit/shell admin",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa … admin@example.com
   -1    66 command="/usr/lib/stagit/shell dilbert",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa … dilbert@example.com
   -1    67 ```
   -1    68 
   -1    69 It is mostly a regular authorized keys file with some restrictions. Most
   -1    70 importantly, the user is restricted to the stagit shell, so no regular shell
   -1    71 access is possible.
   -1    72 
   -1    73 Note that the stagit shell gets the username to use as first argument.
   -1    74 
   -1    75 ## Differences to the originals
   -1    76 
   -1    77 -	General
   -1    78 	-	Everything is stripped down to the essentials (YMMV). That is not to say
   -1    79 		that the missing features are not relevant, but they are not relevant to my
   -1    80 		specific usecase.
   -1    81 	-	The integration between access control and static website is hardcoded,
   -1    82 		which makes it simpler but also less flexible.
   -1    83 -	Compared to stagit
   -1    84 	-	The UI takes some inspiration from github.
   -1    85 	-	README is rendered using [cmark](https://github.com/commonmark/cmark).
   -1    86 	-	I wanted to use a proper (but minimal) templating library but did not find
   -1    87 		one. So I ended up with a crude pre-processing script.
   -1    88 -	Compared to gitolite
   -1    89 	-	Config and keys are not tracked in an admin repository. I can just as well
   -1    90 		log into the server.
   -1    91 	-	If you want to add custom hooks you should add them directly to the source
   -1    92 		code.
   -1    93 	-	The conffile format is different and does not support some advanced
   -1    94 		features.
   -1    95 	-	The access control scripts are implemented in python instead of perl. I
   -1    96 		just don't know much perl, that's why.
   -1    97 
   -1    98 ## Customization
   -1    99 
   -1   100 The source code is meant to be hackable, so feel free to mess around.