From e98f95752ea9137f7d54f58cbbd09da94436b02d Mon Sep 17 00:00:00 2001
From: "Iain R. Learmonth" <irl@fsfe.org>
Date: Tue, 21 Apr 2020 14:36:56 +0100
Subject: [PATCH] git explain gitolite config

---
 git.mdwn | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 4 deletions(-)

diff --git a/git.mdwn b/git.mdwn
index b7b2ed2c..d5278e10 100644
--- a/git.mdwn
+++ b/git.mdwn
@@ -64,18 +64,75 @@ repo metrics-cloud
 metrics-cloud "The Tor Project" = "Configurations for Tor Metrics cloud orchestration"
 ```
 
-The last line of this file is what is used to provide configuration to gitweb.
-In this case, the permissions are delegated to a group and not an individual
-user. Groups are defined at the top of the file, again in alphabetical order:
+Deconstructing this:
 
 ```
-@metrics-cloud                               = karsten irl
+repo metrics-cloud
+```
+
+Starts a repository block.
+
+```
+    RW                                       = @metrics-cloud
+```
+
+Allows non-destructive read/write but not branch/tag deletion or
+non-fast-forward pushes. Alternatives would include "R" for read-only, or
+"RW+" to allow for destructive actions. We only allow destructive actions for
+user's personal repositories.
+
+In this case, the permissions are delegated to a group (starting with @) and
+not an individual user.
+
+```
+    config hooks.email-enabled               = true
+    config hooks.mailinglist                 = tor-commits@lists.torproject.org
+```
+
+This enables the email hook to send one email per commit to the commits list.
+For all top-level repositories, the mailing list should be
+tor-commits@lists.torproject.org.
+
+```
+    config hooks.irc-enabled                 = true
+    config hooks.ircproject                  = or
+```
+
+This enables the IRC hook to send one message per commit to an IRC channel. If
+the project is set to "or" the messages will be sent to #tor-bots.
+
+```
+    config hooks.githuburl                   = torproject/metrics-cloud
+    config hooks.gitlaburl                   = torproject/metrics/metrics-cloud
+```
+
+These enable pushing a mirror to external services. The external service will
+have to be configured to accept these pushes, and we should avoid adding
+mirror URLs where things aren't configured yet so we don't trigger any IPS or
+abuse detection system by making loads of bad push attempts.
+
+```
+metrics-cloud "The Tor Project" = "Configurations for Tor Metrics cloud orchestration"
 ```
 
+The last line of this file is what is used to provide configuration to gitweb.
+Starting with the path, then the owner, then the short description.
+
 Upon push, the new repository will be created. It may take some minutes to
 appear on the gitweb. Do not fear, the old list that did not yet include the
 new repository has just been cached.
 
+Push takes ages. Don't Ctrl-C it or you can end up in an inconsistent state.
+Just let it run. A future git team member might work on backgrounding the
+sync task.
+
+Groups are defined at the top of the file, again in alphabetical order
+(not part of the repository block):
+
+```
+@metrics-cloud                               = karsten irl
+```
+
 ### Adding developers to a repository
 
 If you want access to an existing repository please have somebody who already
-- 
GitLab