improve the comments for better docs

1 files changed, 28 insertions, 10 deletions

diff --git a/config-service-git.PKGBUILD b/config-service-git.PKGBUILD
index 48bd74c..b074cec 100644
--- a/config-service-git.PKGBUILD
+++ b/config-service-git.PKGBUILD
@@ -3,16 +3,10 @@ pkgver=20161111.2
 
 package() {
 preamble
-
-depends+=(config-mgmt-certbot)
-
-add-file -m755 etc/ssl/misc/certbot-get.d/10-git <<EOF
-#!/bin/bash
-echo git.{parabola.nu,parabolagnulinux.org}
-EOF
+# #### Git
 
 depends+=(
-	git # for the 'git' user
+	git # for the 'git' user, and obviously git itself.
 	cronie
 	moreutils # for chronic
 )
@@ -28,19 +22,43 @@ PATH=/srv/git/.local/bin:/bin
 0	*	*	*	*	chronic bash -c "update-gitmeta 'Update from cron' 2>&1"
 EOF
 
-# ## transport: git protocol
+# ##### transport: git protocol
 
 add-unit etc/systemd/system/sockets.target.wants/git-daemon.socket
 
-# ## transport: HTTPS
+# ##### transport: SSH
+
+# Files affected manually:
+#
+# * `/srv/git/git-shell-commands/`
+#
+# This is the only method for which push is enabled. Only the git@
+# user may push; even though if you have access to git, you probably
+# have access to ssh into yourname@winston, you can't push from that
+# account. As far as git is concerned, all users are equal (TODO:
+# perhaps we should implement some more granular access
+# control. Safety rails and all that). Access to git@ is based on
+# membership in the "git" group in hackers.git (see
+# [#Parabola_hackers](#Parabola_hackers)).
+#
+# If you need to set up custom git hooks, then ssh in to your user,
+# and use `sudo -u git` to do it.
+
+# ##### transport: HTTPS
 
 depends+=(
 	cgit
+	config-mgmt-certbot
 	config-mgmt-nginx
 	config-mgmt-uwsgi
 	uwsgi-plugin-cgi
 )
 
+add-file -m755 etc/ssl/misc/certbot-get.d/10-git <<EOF
+#!/bin/bash
+echo git.{parabola.nu,parabolagnulinux.org}
+EOF
+
 # The git web interface is cgit, which is managed by uWSGI speaking
 # uwsgi/modifier1=9, which is the variant of the uwsgi protocol for
 # CGI requests.