877c6625dc
typos, minor clarifications, removing outdated stuff that got missed, adding some emphasis here and there, re-phrasing some places, etc.
243 lines
8.8 KiB
Markdown
243 lines
8.8 KiB
Markdown
# gitolite.conf -- by example
|
|
|
|
I hate people who make statements like "I dont have time to learn". People
|
|
with that sort of attitude shouldn't use gitolite at all, and I refuse to
|
|
spoon-feed them or be their personal tutor.
|
|
|
|
However, it's possible that even with the right attitude and willingness to
|
|
learn, some people just get a mental block about something, and so I figure
|
|
this might help.
|
|
|
|
(Side note: followup questions not welcome from people in the former category;
|
|
you know who you are).
|
|
|
|
**WARNING 1**: in case of conflict between this document and reality, reality
|
|
wins. For conflict between this document and the [main document][conf], the
|
|
main document wins. In any case, please bring such issues to my notice.
|
|
|
|
**WARNING 2**: this document has examples only for the most commonly used
|
|
features. If you don't find a feature here, look in the main document before
|
|
asking me.
|
|
|
|
**WARNING 3**: Read the WHOLE document. I can't keep saying, for instance,
|
|
that "rewind" actually means any of 3 different things so I'll say it only
|
|
once. It's upto you to have read that part also.
|
|
|
|
[conf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
|
|
|
|
----
|
|
|
|
[[TOC]]
|
|
|
|
----
|
|
|
|
### general notes
|
|
|
|
Git branch/tag name **recap**: branches look like refs/heads/something, tags
|
|
look like refs/tags/something. When there is no ambiguity, we leave out the
|
|
refs/heads/ and the refs/tags/.
|
|
|
|
A "rewind" means any of 3 things: force-push a branch (make it go backward,
|
|
using 'git push -f' or equivalent), delete a branch, or update a tag. The
|
|
first two are clearly information-losing operations so it is wise to require
|
|
special rights to do them. The third is in the same category because tags are
|
|
supposed to be "write once" so **re**-writing a tag is considered abnormal.
|
|
|
|
These examples are only for the more complex parts of the conf file. We're
|
|
not going to discuss things like what characters are allowed in a username or
|
|
reponame, how to write a comment line, how to write continuation lines (you
|
|
can't), include files, and all such *lexical* issues.
|
|
|
|
### extremely brief regex overview
|
|
|
|
Regexes are powerful. Gitolite uses that power as much as it can. If you
|
|
can't handle that power, hire someone who can and become a manager.
|
|
|
|
That said, here's a very quick overview of the highlights.
|
|
|
|
`^` and `$` are called "anchors". They anchor the match to the beginning and
|
|
end of the string respectively.
|
|
|
|
^foo matches any string starting with 'foo'
|
|
foo$ matches any string ending with 'foo'
|
|
^foo$ matches exact string 'foo'.
|
|
|
|
To be precise, the last one is "any string starting and ending with *the same*
|
|
'foo'". "foofoo" does not match.
|
|
|
|
`[0-9]` is an example of a character class; it matches any single digit.
|
|
`[a-z]` matches any lower case alpha, and `[0-9a-f]` is the range of hex
|
|
characters. You should now guess what `[a-zA-Z0-9_]` does.
|
|
|
|
`.` (the period) is special -- it matches any character. If you want to match
|
|
an actual period, you need to say `\.`.
|
|
|
|
`*`, `?`, and `+` are quantifiers. They apply to the previous token. `a*`
|
|
means "zero or more 'a' characters". Similarly `a+` means "one or more", and
|
|
`a?` means "zero or one".
|
|
|
|
As a result, `.*` means "any number (including zero) of any character".
|
|
|
|
The previous token need not be a single character; you can use parens to make
|
|
it longer. `(foo)+` matches one or more "foo", (like "foo", "foofoo",
|
|
"foofoofoo", etc.)
|
|
|
|
### basic access control
|
|
|
|
repo gitolite-admin
|
|
RW+ = sitaram
|
|
# this is equivalent to:
|
|
RW+ refs/.* = sitaram
|
|
|
|
Sitaram is the only admin. He can push, create, delete, or rewind any branch
|
|
or tag in the gitolite-admin repo.
|
|
|
|
repo testing
|
|
RW+ = @all
|
|
|
|
The 'testing' repo is a play area for everyone. Anyone can do anything to any
|
|
branch or tag on it.
|
|
|
|
repo foo
|
|
RW+ = sitaram dilbert
|
|
RW = alice ashok
|
|
R = wally
|
|
|
|
Wally can only read the repo. Alice and Ashok can push but not rewind; only
|
|
Sitaram and Dilbert can do that.
|
|
|
|
R master = wally # MEANINGLESS! WILL NOT DO WHAT YOU THINK IT DOES!!
|
|
|
|
This won't work. You can only restrict "read" access at the repo level, not
|
|
at the branch level. This is a git issue, not a gitolite issue. Go bother
|
|
them, or switch to gerrit.
|
|
|
|
repo foo
|
|
RW master$ = dilbert alice
|
|
# this is equivalent to:
|
|
RW refs/heads/master$ = dilbert alice
|
|
|
|
The reason for treating "master$" as "refs/heads/master$" is that matching
|
|
branches is the most common use so the syntax is optimised to make that
|
|
simpler to write and easier to read. Anything *not* starting with `refs/`
|
|
(<font color="gray">or `NAME/`, but that is out of scope for this
|
|
document</font>), is implicitly prefixed with `refs/heads/`.
|
|
|
|
The `master$` is called a "refex" (a regex that matches a ref).
|
|
|
|
Dilbert and Alice can push to the "master" branch. Unless some other rule
|
|
allows it, they cannot push to, say, "master1", "masterfull" etc., due to the
|
|
`$` at the end of the refex.
|
|
|
|
Refexes are *prefix matched*; i.e., treated as if they have a `^` at the
|
|
start. (This means `^refs/heads/master` in this case, not `^master`, in case
|
|
you forgot!)
|
|
|
|
This rule therefore does not match "headmaster", or even
|
|
"refs/heads/refs/heads/master" (<font color="gray">yes, it is possible to
|
|
confuse yourself by pushing a branch like that in git</font>).
|
|
|
|
RW+ pu = dilbert
|
|
# again, remember this is equivalent to:
|
|
RW+ refs/heads/pu = dilbert
|
|
|
|
Dilbert can push any branch whose name starts with "pu". This includes "pu1",
|
|
"pupu", "pu/up", and so on, not just "pu". This is because there is no `$` at
|
|
the end.
|
|
|
|
RW junk/ = wally
|
|
|
|
Wally can push any branch under "junk/", which means "junk/foo", "junk/bar",
|
|
are ok but not "junk1" or even "junk".
|
|
|
|
RW tmp/ = @all
|
|
|
|
Similar to above, but for *any* authenticated user.
|
|
|
|
RW refs/tags/v[0-9] = ashok # the QA guy
|
|
|
|
Ashok is allowed to push version tags. He can push any tag whose name starts
|
|
with a "v", then a digit, like "v1", "v1.0", "v2.0rc1", etc., but not "v-1",
|
|
"ver1".
|
|
|
|
### advanced access control
|
|
|
|
#### "deny" rules
|
|
|
|
**Warning**: When using deny rules, the order of your rules matters, where
|
|
earlier it did not.
|
|
|
|
PROCESSING LOGIC:
|
|
|
|
> The first matching refex that has the permission you're looking for (`W`
|
|
> or `+`) **or a minus (`-`)**, results in success **or failure,
|
|
> respectively**. A fallthrough **also** results in failure.
|
|
|
|
RW refs/tags/v[0-9] = ashok
|
|
- refs/tags/v[0-9] = @staff
|
|
RW refs/tags = @staff
|
|
|
|
This allows only Ashok to write "version tags" (see rule for Ashok the QA guy
|
|
somewhere above). The others can write any tags they want, *except* version
|
|
tags. To understand this, try and match each rule *in sequence* with the name
|
|
of the tag being pushed, and the user doing it, applying the logic described
|
|
earlier.
|
|
|
|
* for non-version tags, only the 3rd rule matches, so anyone on staff can
|
|
push them
|
|
* for version tags by ashok, the first rule matches so he can push them
|
|
* for version tags by staffers *other than ashok*, the second rule matches
|
|
before the third one, and it has a `-` as the permission, so the push
|
|
fails
|
|
|
|
#### personal branches
|
|
|
|
Personal branches exist **in a namespace** of their own. The syntax is
|
|
|
|
RW personal/USER/ = @staff
|
|
|
|
where the "personal" can be anything you like (but cannot be empty), and the
|
|
"/USER/" part is **necessary**. A user "alice" can then push any branches
|
|
inside `personal/alice/`. Which means she can push `personal/alice/foo` and
|
|
`personal/alice/bar`, but NOT `personal/alice`.
|
|
|
|
#### splitting up rules into rulesets
|
|
|
|
Rules accumulate. Even when separated by rules for other repos. They
|
|
accumulate intuitively. For example:
|
|
|
|
repo foo
|
|
RW+ = alice
|
|
|
|
repo bar
|
|
RW+ = dilbert
|
|
|
|
repo @all
|
|
RW dev/USER/ = @staff
|
|
|
|
repo foo
|
|
RW+ tmp/ = @staff
|
|
|
|
has the **effective** ruleset, for repo foo, of
|
|
|
|
repo foo
|
|
RW+ = alice
|
|
RW dev/USER/ = @staff
|
|
RW+ tmp/ = @staff
|
|
|
|
Just remember that if you use [deny rules][dr] anywhere then the *order of the
|
|
rules matters*!
|
|
|
|
[dr]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_deny_rules
|
|
|
|
#### gitweb and daemon
|
|
|
|
Gitolite does NOT do anything for gitweb and daemon access **except**
|
|
|
|
* for daemon, create the file `git-daemon-export-ok` in the repository
|
|
* for gitweb, add the repo (plus owner name, if given) to the list of
|
|
projects to be served by gitweb (see the config file variable
|
|
`$PROJECTS_LIST`, which should have the same value you specified for
|
|
`$projects_list` when setting up gitweb)
|
|
* put the description, if given, in `$repo/description`
|