Browse files

newrc doc

  • Loading branch information...
1 parent 5ee08fa commit 9d1a3dd7e6286a9690cd60df65ad81dfa4da86c5 @sitaramc committed Mar 3, 2013
Showing with 145 additions and 37 deletions.
  1. +4 −4 cust.mkd
  2. +4 −9 extras/sts.mkd
  3. +3 −4 g2migr.mkd
  4. +6 −9 g3why.mkd
  5. +2 −2 locking.mkd
  6. +1 −1 non-core.mkd
  7. +1 −2 perf.mkd
  8. +111 −0 rc-33.mkd
  9. +10 −4 rc.mkd
  10. +3 −2 triggers.mkd
View
8 cust.mkd
@@ -27,7 +27,7 @@ TOC
There are 5 basic types of non-core programs.
* *Commands* can be run from the shell command line. Among those, the ones
- listed in the COMMANDS hash of the rc file can also be run remotely.
+ in the ENABLE list in the rc file can also be run remotely.
* *Hooks* are standard git hooks.
* *Sugar scripts* change the conf language for your convenience. The word
sugar comes from "syntactic sugar".
@@ -122,7 +122,7 @@ You can get a **list of available commands** by using the `help` command.
Naturally, a remote user will see a much smaller list than the server user.
You allow a command to be run from remote clients by adding its name to (or
-uncommenting it if it's already added but commented out) the COMMANDS hash in
+uncommenting it if it's already added but commented out) the ENABLE list in
the [rc][] file.
### #hooks hooks and gitolite
@@ -154,8 +154,8 @@ lines), while the parser in the core gitolite engine does not change.
If you want to write your own sugar scripts, please read the "your own sugar"
section in [dev-notes][] first then email me.
-You enable a sugar script by adding it to the `SYNTACTIC_SUGAR` list in the rc
-file.
+You enable a sugar script by uncommenting the feature name in the ENABLE list
+in the rc file.
### triggers
View
13 extras/sts.mkd
@@ -169,12 +169,7 @@ To do this:
SHELL_USERS_LIST => "$ENV{HOME}/.gitolite.shell-users",
- * 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.
+ * enable the trigger by uncommenting the 'Shell' line in the ENABLE list.
Then run `gitolite compile; gitolite trigger POST_COMPILE` or push a dummy
change to the admin repo.
@@ -188,11 +183,11 @@ fingerprint of the key that finally matched, so normally all you have is the
However, if you replace
- 'post-compile/ssh-authkeys',
+ 'ssh-authkeys',
-in the `POST_COMPILE` trigger list in the rc file with
+in the ENABLE list with
- 'post-compile/ssh-authkeys --key-file-name',
+ 'ssh-authkeys --key-file-name',
then an extra argument is added after the username in the "command" variable
of the authkeys file. That is, instead of this:
View
7 g2migr.mkd
@@ -71,10 +71,9 @@ Some of them have links where there is more detail than I want to put here.
* `GL_NO_DAEMON_NO_GITWEB` **dropped**, **requires presetting**. Default
will clobber your projects.list file and git-daemon-export-ok files.
- Comment out the appropriate lines in the rc file, in the `POST_COMPILE`
- *and* the `POST_CREATE` trigger sections. As a bonus, gitweb and daemon
- can now be separately disabled, instead of both being tied to the same
- setting.
+ Comment out the 'daemon' and 'gitweb' lines in the ENABLE list in the rc
+ file. As you can see, gitweb and daemon can now be separately disabled,
+ instead of both being tied to the same setting.
* `GL_NO_SETUP_AUTHKEYS` **dropped**, **requires presetting**. Default will
clobber your authkeys file.
View
15 g3why.mkd
@@ -60,15 +60,12 @@ So, briefly, here are the advantages of g3:
write your own, though they do have to be in perl (because they're not
standalone programs).
- Once the code is written and placed in the right place, all a site has to
- do to enable it is to uncomment some lines in the rc file:
-
- # these will run in sequence during the conf file parse
- SYNTACTIC_SUGAR =>
- [
- # 'continuation-lines',
- # 'keysubdirs-as-groups',
- <etc>
+ Once the code is written and placed in the right place, all you have to do
+ to enable it is to uncomment some lines in the ENABLE list in the rc file:
+
+ # 'continuation-lines',
+ # 'keysubdirs-as-groups',
+ <etc>
* roll your own
View
4 locking.mkd
@@ -31,8 +31,8 @@ into a "merge" situation.
## admin/setup
-First, someone with shell access to the server must add 'lock' to the
-"COMMANDS" list in the rc file.
+First, someone with shell access to the server must add 'lock' to the ENABLE
+list in the rc file.
Next, the gitolite.conf file should have something like this:
View
2 non-core.mkd
@@ -163,7 +163,7 @@ can't do this for files and directories.
Here's how:
-1. enable 'partial-copy' in the `PRE_GIT` section in the rc file.
+1. enable 'partial-copy' in the ENABLE list in the rc file.
2. for each repo "foo" which has secret branches that a certain set of
developers (we'll use a group called `@temp-emp` as an example) are not
View
3 perf.mkd
@@ -17,8 +17,7 @@ list. Meanwhile, here are some tips:
* If you don't use gitweb or git-daemon, or use them but are perfectly happy
to control access to them from outside gitolite, you can comment out the
- corresponding lines in the POST\_CREATE and POST\_COMPILE trigger lists in
- the rc file.
+ corresponding lines in the ENABLE list the rc file.
* If you can't get rid of those scripts, and they are still taking too long,
you can make them run in the background. They'll eventually finish but
View
111 rc-33.mkd
@@ -0,0 +1,111 @@
+# the v3.0 to v3.3 "rc" file (`$HOME/.gitolite.rc`)
+
+**NOTE 1**: if you're using v3.4 and above, see [this][rc].
+
+**NOTE 2**: if you're migrating from g2, there are some settings that MUST be
+dealt with **before** running `gitolite setup`; please read the
+[migration][migr] page and linked pages, and especially the one on "presetting
+the rc file"
+
+----
+
+The rc file for g3 is *quite* different from that of g2.
+
+As before, it is designed to be the only thing unique to your site for most
+setups. What is new is that it is easy to extend it when new needs come up,
+without having to touch core gitolite.
+
+The rc file is perl code, but you do NOT need to know perl to edit it. Just
+mind the commas, use single quotes unless you know what you're doing, and make
+sure the brackets and braces stay matched up!
+
+Please look at the `~/.gitolite.rc` file that gets installed when you setup
+gitolite. As you can see there are 3 types of variables in it:
+
+ * simple variables (like `UMASK`)
+ * lists (like `POST_COMPILE`, `POST_CREATE`)
+ * hashes (like `ROLES`, `COMMANDS`)
+
+While some of the variables are documented in this file, many of them are not.
+Their purposes are to be found in each of their individual documentation files
+around; start with [customising gitolite][cust]. If a setting is used by an
+external command then running that command with '-h' may give you additional
+information.
+
+## specific variables
+
+ * `$UMASK`, octal, default `0077`
+
+ The default UMASK that gitolite uses makes all the repos and their
+ contents have `rwx------` permissions. People who want to run gitweb
+ realise that this will not do.
+
+ The correct way to deal with this is to give this variable a value like
+ `0027` (note the syntax: the leading 0 is required), and then make the
+ user running the webserver (apache, www-data, whatever) a member of the
+ 'git' group.
+
+ If you've already installed gitolite then existing files will have to be
+ fixed up manually (for a umask or 0027, that would be `chmod -R g+rX`).
+ This is because umask only affects permissions on newly created files, not
+ existing ones.
+
+ * `$GIT_CONFIG_KEYS`, string, default empty
+
+ This setting allows the repo admin to define acceptable gitconfig keys.
+
+ Gitolite allows you to set git config values using the "config" keyword;
+ see [here][git-config] for details and syntax.
+
+ However, if you are in an installation where the repo admin does not (and
+ should not) have shell access to the server, then allowing him to set
+ arbitrary repo config options *may* be a security risk -- some config
+ settings allow executing arbitrary commands!
+
+ You have 3 choices. By default `$GIT_CONFIG_KEYS` is left empty, which
+ completely disables this feature (meaning you cannot set git configs via
+ the repo config).
+
+ The second choice is to give it a space separated list of settings you
+ consider safe. (These are actually treated as a set of [regular
+ expression][regex] patterns, and any one of them must match).
+
+ For example:
+
+ $GIT_CONFIG_KEYS = 'core\.logAllRefUpdates core\..*compression';
+
+ Each pattern should match the *whole* key (in other words, there
+ is an implicit `^` at the start of each pattern, and a `$` at the
+ end).
+
+ The third choice (which you may have guessed already if you're familiar
+ with regular expressions) is to allow anything and everything:
+ `$GIT_CONFIG_KEYS = '.*';`
+
+ * `ROLES`, hash, default keys 'READERS' and 'WRITERS'
+
+ This specifies the role names allowed to be used by users running the
+ [perms][] command. The [wild][] repos doc has more info on roles.
+
+ * `DEFAULT_ROLE_PERMS`, string, default undef
+
+ This sets default wildcard permissions for newly created wildcard repos.
+
+ If set, this value will be used as the default role permissions for new
+ wildcard repositories. The user can change this value with the perms
+ command as desired after repository creation; it is only a default.
+
+ Please be aware this is potentially a multi-line variable. In most
+ setups, it will be left undefined. Some installations may benefit from
+ setting it to `READERS @all`.
+
+ If you want multiple roles to be assigned by default, here is how. Note
+ double quotes this time, due to the embedded newline, which in turn
+ require the '@' to be escaped:
+
+ DEFAULT_ROLE_PERMS => "READERS \@all\nWRITERS \@senior_devs",
+
+ * `LOCAL_CODE`, string
+
+ This is described in more detail [here][localcode]. Please be aware
+ **this must be a FULL path**, not a relative path.
View
14 rc.mkd
@@ -1,6 +1,12 @@
# the "rc" file (`$HOME/.gitolite.rc`)
-**NOTE**: if you're migrating from g2, there are some settings that MUST be
+**IMPORTANT**: if you have a v3.0-v3.3 rc file it will still work. In fact
+internally the v3.4 rc file data gets converted to the v3.3 format. So just
+because you upgraded gitolite doesn't mean you have to change your rc file!
+
+**v3.3 or before**: [this][rc-33] is the document you need.
+
+**NOTE 2**: if you're migrating from g2, there are some settings that MUST be
dealt with **before** running `gitolite setup`; please read the
[migration][migr] page and linked pages, and especially the one on "presetting
the rc file"
@@ -20,9 +26,9 @@ sure the brackets and braces stay matched up!
Please look at the `~/.gitolite.rc` file that gets installed when you setup
gitolite. As you can see there are 3 types of variables in it:
- * simple variables (like `UMASK`)
- * lists (like `POST_COMPILE`, `POST_CREATE`)
- * hashes (like `ROLES`, `COMMANDS`)
+ * a lot of simple variables (like `UMASK`, `GIT_CONFIG_KEYS`, etc)
+ * a hash or two (like `ROLES`)
+ * and one large list of features to be enabled (`ENABLE`)
While some of the variables are documented in this file, many of them are not.
Their purposes are to be found in each of their individual documentation files
View
5 triggers.mkd
@@ -6,7 +6,8 @@ TOC
Gitolite fires off external commands at 7 different times. The [rc][] file
specifies what commands to run at each trigger point, but for illustration,
-here's an excerpt:
+here's an excerpt. **Note that as of v3.4, this is *not* how the rc file
+looks like externally; please see the [rc file docs][rc] for more**.
%RC = (
@@ -70,7 +71,7 @@ require any arguments, so it works).
Triggers receive the following arguments:
1. any arguments mentioned in the rc file (for an example, see the renice
- command in the PRE_GIT trigger sequence),
+ command)
2. the name of the trigger as a string (example, `"POST_COMPILE"`), so you
can call the same program from multiple triggers and it can know where it

0 comments on commit 9d1a3dd

Please sign in to comment.