diff --git a/doc/dev-notes.mkd b/doc/dev-notes.mkd index 040198c..501d44f 100644 --- a/doc/dev-notes.mkd +++ b/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. (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). + +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]. diff --git a/doc/extras/sts.mkd b/doc/extras/sts.mkd index b9a5e7d..279a82f 100644 --- a/doc/extras/sts.mkd +++ b/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,7 +168,9 @@ 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. @@ -176,7 +178,7 @@ To do this: 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 diff --git a/doc/locking.mkd b/doc/locking.mkd index f693ed5..2799003 100644 --- a/doc/locking.mkd +++ b/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. diff --git a/doc/non-core.mkd b/doc/non-core.mkd index b893e0a..2ad98d8 100644 --- a/doc/non-core.mkd +++ b/doc/non-core.mkd @@ -45,16 +45,28 @@ The following "sugar" programs are available: ## triggers +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. + +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: - * partial-copy -- this has its own section later in this page. - * 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: diff --git a/doc/triggers.mkd b/doc/triggers.mkd index 3c19496..d25a0bd 100644 --- a/doc/triggers.mkd +++ b/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: diff --git a/src/lib/Gitolite/Rc.pm b/src/lib/Gitolite/Rc.pm index e990e06..8dbe1e7 100644 --- a/src/lib/Gitolite/Rc.pm +++ b/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', ],