Permalink
Browse files

(accumulated docfixes) esp a large section on the INPUT trigger

  • Loading branch information...
1 parent 17c41ce commit f59ad8cafce78d55af6be2b167726492d69bccc9 @sitaramc committed May 30, 2012
Showing with 109 additions and 16 deletions.
  1. +48 −0 doc/dev-notes.mkd
  2. +5 −3 doc/extras/sts.mkd
  3. +8 −1 doc/locking.mkd
  4. +16 −4 doc/non-core.mkd
  5. +21 −0 doc/triggers.mkd
  6. +11 −8 src/lib/Gitolite/Rc.pm
View
48 doc/dev-notes.mkd
@@ -115,3 +115,51 @@ contents modified as you like and return a ref to it.
There are a couple of examples in src/syntactic-sugar.
+## appendix 1: notes on the INPUT trigger
+
+Note: some of this won't make sense if you haven't read about [triggers][].
+
+The INPUT trigger sequence is designed to set or change environment variables
+or the argument list. (Side note: this means INPUT triggers have to be
+written as perl modules; they cannot be standalone scripts). This is a very
+powerful idea so an extended description may be useful.
+
+Sshd invokes gitolite-shell with the SSH\_ORIGINAL\_COMMAND env var containing
+the git/gitolite command and one argument: the gitolite username.
+
+ * see [this][glssh] for details on the latter
+ * the *first* thing gitolite does in smart http mode is to use the
+ REMOTE\_USER and the CGI variables that apache provides to *construct*
+ a fake argument list and a fake SSH\_ORIGINAL\_COMMAND env var, so the
+ rest of the code can stay the same
+
+The INPUT trigger is then run. The purpose of the input trigger is to ensure
+that the first argument *is* the gitolite username, and that the
+SSH\_ORIGINAL\_COMMAND env var contains the actual command to execute. It can
+also be used to set up any other environment variables that you may decide you
+need.
+
+Wait... didn't we say that's what gitolite-shell gets anyway, just now?
+
+Well, we lied a bit there; it's not always true!
+
+For example, if [this][giving-shell] feature is used, the first argument *may*
+be "-s", with the username in the *second* argument. Shell.pm deals with
+that. <font color="gray">(Order matters. If you use this feature, put the
+`'Shell::input',` line ahead of the others, since it is the only one prepared
+to deal with username not being the first argument).</font>
+
+If you look at CpuTime.pm, you'll see that it's `input()` function doesn't set
+or change anything, but does set a package variable to record the start time.
+Later, when the same module's `post_git()` function is invoked, it uses this
+variable to determine elapsed time.
+
+*(This is a very nice and simple example of how you can implement features by
+latching onto multiple events and sharing data to do something)*.
+
+You can even change the reponame the user sees, behind his back. Alias.pm
+handles that.
+
+Finally, as an exercise for the reader, consider how you would create a brand
+new env var that contains the *comment* field of the ssh pubkey that was used
+to gain access, using the information [here][kfn].
View
8 doc/extras/sts.mkd
@@ -153,7 +153,7 @@ Done? OK, now the general outline for ssh troubleshooting is this:
## random tips, tricks, and notes
-### giving shell access to gitolite users
+### #giving-shell giving shell access to gitolite users
Thanks to an idea from Jesse Keating, a single key can allow both gitolite
access *and* shell access.
@@ -168,15 +168,17 @@ To do this:
SHELL_USERS_LIST => "$ENV{HOME}/.gitolite.shell-users",
- * add the line `'Shell::input',` to the `INPUT` list in the rc file.
+ * add the line `'Shell::input',` to the `INPUT` list in the rc file. This
+ must be the first item on the list (possibly preceded by CpuTime, if
+ you're using that).
* add the line `'post-compile/ssh-authkeys-shell-users',` to the
`POST_COMPILE` list, *after* the `'post-compile/ssh-authkeys',` line.
Then run `gitolite compile; gitolite trigger POST_COMPILE` or push a dummy
change to the admin repo.
-### distinguishing one key from another
+### #kfn distinguishing one key from another
Since a user can have [more than one key][multi-key], it is sometimes useful
to distinguish one key from another. Sshd does not tell you even the
View
9 doc/locking.mkd
@@ -12,7 +12,12 @@ this situation it should be possible to at least prevent commits from being
pushed that contains changes to files locked by someone else.
The two "lock" programs (one a command that a user uses, and one a VREF that
-the admin adds to a repo's access rules) together achieve this.
+the admin adds to a repo's access rules) together attempt to achieve this.
+
+Of course, locking by itself is not quite enough. You may still get into
+merge situations if you make changes in branches. For best results you should
+actually keep all the binary files in their own branch, separate from the ones
+containing source code.
----
@@ -50,6 +55,8 @@ Here's a summary:
For best results, everyone on the team should:
+ * Switch to the branch containing the binary files when wanting to make a
+ change.
* Run 'git pull' or eqvt, then lock the binary file(s) before editing them.
* Finish the editing task as quickly as possible, then commit, push, and
unlock the file(s) so others are not needlessly blocked.
View
20 doc/non-core.mkd
@@ -45,16 +45,28 @@ The following "sugar" programs are available:
## triggers
-The `PRE_GIT` triggers are:
+Note that some features need to be enabled in more than one trigger.
+Mirroring is probably the best example -- it needs to hook into the `INPUT`,
+`PRE_GIT`, and the `POST_GIT` triggers to work.
- * partial-copy -- this has its own section later in this page.
+The `INPUT` triggers are:
+
+ * CpuTime -- see the `POST_GIT` section below
+ * Shell -- see "giving shell access to gitolite users" in [this][sts] page.
+ * Alias -- documentation is within the source file Alias.pm
+ * Mirroring -- see [doc/mirroring.mkd][mirroring]
+
+The `PRE_GIT` triggers are:
* renice -- this renices the entire job to whatever value you specify.
+ * Mirroring -- see [doc/mirroring.mkd][mirroring]
+ * partial-copy -- this has its own section later in this page.
The `POST_GIT` triggers are:
- * CpuTime, which is only a sample because it only prints the CPU times data.
- In reality you will want to do something else with it.
+ * Mirroring -- see [doc/mirroring.mkd][mirroring]
+ * CpuTime -- this is only a sample because it only prints the CPU times
+ data. In reality you will want to do something else with it.
The `POST_COMPILE` triggers are:
View
21 doc/triggers.mkd
@@ -32,6 +32,27 @@ here's an excerpt:
(As you can see, post-create runs 3 programs that also run from post-compile.
This is perfectly fine, by the way)
+## types of trigger programs
+
+There are two types of trigger programs. Standalone scripts are placed in
+src/triggers or its subdirectories. They are invoked by being added to a
+trigger list (using the path after "src/triggers/", as you can see). Such
+scripts are quick and easy to write in any language of your choice.
+
+Triggers written as perl modules are placed in src/lib/Gitolite/Triggers.
+They are invoked by being listed with the package+function name, although even
+here the 'Gitolite::Triggers' part is skipped. Perl modules have to follow
+some conventions (see some of the shipped modules to ideas) but the advantage
+is that they can set environment variables and change the argument list of the
+gitolite-shell program that invokes them.
+
+If this does not make sense, please examine a default install of gitolite,
+paying attention to:
+
+ * the path names in various trigger lists in the rc file
+ * corresponding path names in the src/ directory in gitolite source
+ * and for perl modules, the package names and function names within.
+
## manually firing triggers
...from the server command line is easy. For example:
View
19 src/lib/Gitolite/Rc.pm
@@ -291,6 +291,14 @@ __DATA__
# (Tip: perl allows a comma after the last item in a list also!)
+# HELP for commands (see COMMANDS list below) can be had by running the
+# command with "-h" as the sole argument.
+
+# HELP for all the other external programs (the syntactic sugar helpers and
+# the various programs/functions in the 8 trigger lists), can be found in
+# doc/non-core.mkd (http://sitaramc.github.com/gitolite/non-core.html) or in
+# the corresponding source file itself.
+
%RC = (
# if you're using mirroring, you need a hostname. This is *one* simple
# word, not a full domain name. See documentation if in doubt
@@ -344,15 +352,16 @@ __DATA__
SYNTACTIC_SUGAR =>
[
# 'continuation-lines',
+ # 'keysubdirs-as-groups',
],
# comment out or uncomment as needed
# these will run in sequence to modify the input (arguments and environment)
INPUT =>
[
- # if you use this, make this the first item in the list
# 'CpuTime::input',
-
+ # 'Shell::input',
+ # 'Alias::input',
# 'Mirroring::input',
],
@@ -366,12 +375,8 @@ __DATA__
# these will run in sequence just before the actual git command is invoked
PRE_GIT =>
[
- # if you use this, make this the first item in the list
# 'renice 10',
-
# 'Mirroring::pre_git',
-
- # see docs ("list of non-core programs shipped") for details
# 'partial-copy',
],
@@ -386,8 +391,6 @@ __DATA__
POST_GIT =>
[
# 'Mirroring::post_git',
-
- # if you use this, make this the last item in the list
# 'CpuTime::post_git',
],

0 comments on commit f59ad8c

Please sign in to comment.