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

This commit is contained in:
Sitaram Chamarty 2012-05-30 14:14:29 +05:30
parent 17c41ce63b
commit f59ad8cafc
6 changed files with 109 additions and 16 deletions

View file

@ -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 file

@ -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

View file

@ -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 file

@ -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:

View file

@ -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 file

@ -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',
],