Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also compare across forks.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also compare across forks.
  • 2 commits
  • 7 files changed
  • 0 commit comments
  • 1 contributor
Commits on Mar 16, 2013
@sitaramc vref: third rewrite.
(I think it's the 3rd.  Can't remember now)
Commits on Mar 24, 2013
@sitaramc DEFAULT_ROLE_PERMS replaced by per repo default.roles option 1fcc6c8
2  cookbook.mkd
@@ -181,7 +181,7 @@ something like this:
2. write your hook code with this at the top:
# check if @foo is in the list of groups of which $GL_REPO is a member
- gitolite list-memberships $GL_REPO | grep -x @foo >/dev/null || exit 0
+ gitolite list-memberships -r $GL_REPO | grep -x @foo >/dev/null || exit 0
3. now add your hook as described in earlier steps
2  g2migr.mkd
@@ -106,7 +106,7 @@ Some of them have links where there is more detail than I want to put here.
+ * `GL_WILDREPOS_DEFPERMS` -- is gone; see [roles][] for how to do this.
* `REPO_BASE` -- **dropped**, is now at a fixed location: `~/repositories`.
If you want it somewhere else go ahead and move it, then place a symlink
27 rc.mkd
@@ -91,23 +91,26 @@ information.
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
+ * `OWNER_ROLENAME`, string, default undef
- This sets default wildcard permissions for newly created wildcard repos.
+ (requires v3.5 or later)
- 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.
+ By default, permissions on a wild repo can only be set by the *creator* of
+ the repo (using the [perms][] command). But some sites want to allow
+ other people to do this as well.
- 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`.
+ To enable this behaviour, the server admin must first set this variable to
+ some string, say 'OWNERS'. (He must also add 'OWNERS' to the ROLES hash
+ described in the previous bullet).
- 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:
+ The creator of the repo can then add other users to the OWNERS role using
+ the [perms][] command.
- DEFAULT_ROLE_PERMS => "READERS \@all\nWRITERS \@senior_devs",
+ The [perms][] command, the new "owns" command, and possibly other commands
+ in future, will then give these users the same privileges that they give
+ to the creator of the repo.
+ (Also see the full documentation on [roles][]).
* `LOCAL_CODE`, string
5 refex.mkd
@@ -10,8 +10,9 @@ In addition:
RW = alice
- * A refex not starting with `refs/` is assumed to start with `refs/heads/`.
- This means normal branches can be conveniently written like this:
+ * A refex not starting with `refs/` <font color="gray">(or `VREF/`)</font>
+ is assumed to start with `refs/heads/`. This means normal branches can be
+ conveniently written like this:
RW master = alice
# becomes 'refs/heads/master' internally
2  user.mkd
@@ -84,7 +84,7 @@ To give some flexibility to users, the admin could add rules like this:
-(he could also add other roles but then he needs to read the documentation).
+(he could also add other [roles][] but then he needs to read the documentation).
Once he does this, you can then use the `perms` command (run `ssh git@host
perms -h` for help) to set permissions for other users by specifying which
101 vref.mkd
@@ -10,65 +10,80 @@ TOC
+VREFs are a mechanism to add additional constraints to a push.
Here's an example to start you off.
- repo r1
- RW+ = lead_dev dev2 dev3
- - VREF/COUNT/9 = dev2 dev3
- - VREF/COUNT/3/NEWFILES = dev2 dev3
+To disallow junior developers from changing more than five files, or from
+touching the Makefile, you can do this:
-Now dev2 and dev3 cannot push changes that affect more than 9 files at a time,
-nor those that have more than 3 new files.
+ repo foo
+ RW+ = @all-devs
+ - VREF/COUNT/5 = @junior-devs
+ - VREF/NAME/Makefile = @junior-devs
-## rule matching recap
+## basic use
-You won't get any joy out of this if you don't understand at least
-[refex][]es and how [rules][] are processed.
+Normally, rules deal with branches and tags (which git collectively calls
+"refs"). The "ref" is a property of the push which gitolite checks against
+the set of rules.
-But VREFs have one **very important difference** from normal rules. With
-VREFs, a **fallthru results in success**. You'll see why this is more
-convenient as you read on.
+VREFs ("virtual refs") are other properties of a push that gitolite can be
+told to check, in addition to the normal ref. For example, "this push has
+more than 5 changed files" could be one property. Or "this push changed the
+file called Makefile" could be another.
-## what is a virtual ref?
+The simplest way to use them is as *additional* "deny" rules to fail a push
+that might otherwise have passed. This is what the example at the top shows.
+Using VREFs like this does not require any great understanding of, or thinking
+about, how they work under the hood.
-We know that "refs/heads/master" and such are normal git refs that are matched
-against the [rules][] to decide if the push is to be allowed or denied.
+## advanced use
-A VREF is just another ref that is checked against the rules. For example,
-VREF/COUNT/5 means "this push has more than 5 changed files". Or
-VREF/NAME/Makefile means "the file called Makefile was changed in this push".
+More complex uses are possible, but may be harder to understand. You may want
+to experiment with the rules to solidify your understanding as you read this.
-## how do I use a VREF?
+### differences from normal refs
-Simple. To disallow junior developers from changing more than five files, or
-from touching the Makefile, you do this:
+We know where normal refs (like "refs/heads/master" or "refs/tags/v1.0") come
+from -- they are supplied by git itself when it calls the update hook.
- repo foo
- RW+ = @all-devs
- - VREF/COUNT/5 = @junior-devs
- - VREF/NAME/Makefile = @junior-devs
+VREFs have two differences with normal refs:
+ * gitolite has to generate them somehow
+ * fallthru is success, not failure
+Here's some more detail on how it works.
+ * first, the normal ("real") ref is checked.
-## where do VREFs come from?
+ As you already know, the push dies if the ref hits a deny rule **or** it
+ falls through without hitting an allow rule.
-From a VREF-maker of course!
+ * next, VREFs are generated and checked one by one.
-## ok who calls the VREF-maker?
+ We'll talk about the generaton later, but for the check, a VREF dies (and
+ kills the push) *only* if it meets an explicit deny rule ("-"). Fallthru
+ does *not* cause failure of a VREF.
-Gitolite. It looks at each rule that contains a VREF rule (there are 2 in the
-above example) and calls VREF-makers for each of them.
+ [refex][] and [rules][] still apply, but several parts of the latter are
+ just not relevant to VREFs (since VREFs only run from the update hook).
+ Plus of course, as we said, fallthru is not a failure now.
-This only happens if the "real" ref (e.g., 'refs/heads/master',
-'refs/tags/v1.0', etc) passes the access rules for the user. If the real ref
-fails, the program dies anyway, and none of the VREF stuff runs.
+### generating virtual refs
-## how does a VREF-maker work?
+Gitolite uses the VREF rules themselves to help it generate the virtual refs.
+Specifically, it looks at each rule that contains a VREF (there are 2 in the
+above example) and calls a VREF-maker for each of them.
We'll take the COUNT example rule above.
When gitolite sees that rule, it calls the "COUNT" VREF-maker. Specifically,
-the `VREF/COUNT` program (See [here][cust] for actual locations on disk).
+this is the `VREF/COUNT` program (See [here][cust] for actual locations on
Gitolite passes it the string "5" as an argument (actually, as the *eighth*
argument; details later).
@@ -81,13 +96,17 @@ two things:
* otherwise it should print nothing.
-It should exit with an exit code of zero in either case. See next section for
+It should exit with an exit code of zero in either case.
+If it exits with a non-zero, the push dies regardless of what is printed (see
+"mimicking a plain old update hook" for why this is useful).
-## mimicking a plain old update hook
+## more details and nuances
-If it exists with a non-zero exit code, then regardless of what it prints or
-does not, the push dies.
+### mimicking a plain old update hook
+If the VREF maker exists with a non-zero exit code, then regardless of what it
+prints or does not, the push dies.
This is just like a plain 'update' hook. Since the first 3 arguments (see
later) are also the same that a plain 'update' hook receives, you can actually
@@ -102,8 +121,6 @@ this rule to your repos:
That's it.
-## details
### what if the VREF-maker prints a different VREF?
Unless you know what you're upto, don't do that.
33 wild.mkd
@@ -104,7 +104,7 @@ metacharacters.
> ----
-## roles
+## #roles roles
The tokens READERS and WRITERS are called "role" names. The access rules in
the conf file decide what permissions these roles have, but they don't say
@@ -115,7 +115,7 @@ You can run `ssh git@host perms -h` for detailed help, but in brief, that
command lets you give and take away roles to users. [This][perms] has some
more detail.
-## adding other roles
+### adding other roles
If you want to have more than just the 2 default roles, say something like:
@@ -132,7 +132,34 @@ You can add the new names to the ROLES hash in the `~/.gitolite.rc` file; see
comments in that file for how to do that. Be sure to run the 2 commands
mentioned there after you have added the roles.
+### setting default roles
+You can setup some default role assignments as soon as a new wild repo is
+Here's how:
+ * enable the 'set-default-roles' feature in the rc file by uncommenting it
+ if it is already present or adding it to the ENABLE list if it is not.
+ * supply a set of default role assignments for a wild repo pattern by adding
+ lines like this to the repo config para:
+ option default.roles-1 = READERS @all
+ option default.roles-2 = WRITERS @senior-devs
+This will then behave as if the [perms][] command was used immediately after
+the repo was created to add those two role assignments.
+If you want to simulate the old (pre v3.5) `DEFAULT_ROLE_PERMS` rc file
+variable, just add them under a `repo @all` line. (Remember that this only
+affects newly created wild repos, despite the '@all' name).
+### specifying owners
+See the section on `OWNER_ROLENAME` in the [rc file documentation][rc].
+#### #rolenamewarn <font color="red">**IMPORTANT WARNING ABOUT THIS FEATURE**</font>
Please make sure that none of the role names conflict with any of the user
names or group names in the system. For example, if you have a user called

No commit comments for this range

Something went wrong with that request. Please try again.