deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

more doc revamp; some notes below

Browse source 
- all anchors prefixed by AUTO_ now
  - some bad links fixed (maybe still a few I didn't catch)
  - misc wording changes/additions (support section to README,
    "technical skills" section to install doc, etc).
This commit is contained in:
Sitaram Chamarty 2010-09-02 19:15:32 +05:30
parent 3559c1190e
commit 5f342c0444
18 changed files with 527 additions and 425 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
README.mkd
View file

@ -1,3 +1,5 @@
<a name="start"></a>
# gitolite
Gitolite is an access control layer on top of git, which allows access control
@ -8,45 +10,39 @@ Gitolite comes with a **huge** amount of documentation. If you're absolutely
new, the suggested reading order is this:
* the README (this document) for a quick intro
* **IMPORTANT:** if you don't know anything about ssh, read [this][doc9gas]
* the [INSTALL][install] document
* if you run into trouble with ssh, read [this][doc6sts]
* the [ADMIN][admin] document
* if you're migrating from gitosis, read [this][migr]
If you run into trouble start [here](#support). If you're migrating from
gitosis, read [this][migr].
Once you've installed it and started using it, you'll want to explore some of
the more powerful features. All the documentation is available in the source
repo as well as [online][docs]. All the longer documents have tables of
contents, so you can quickly get a feel for what is covered right at the top.
[install]: http://github.com/sitaramc/gitolite/blob/master/doc/0-INSTALL.mkd
[admin]: http://github.com/sitaramc/gitolite/blob/master/doc/2-admin.mkd
[migr]: http://github.com/sitaramc/gitolite/blob/master/doc/1-migrate.mkd
[docs]: http://github.com/sitaramc/gitolite/blob/pu/doc
[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-gitolite-and-ssh.mkd
[doc6sts]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd
----
In this document:
* <a href="#what">what</a>
* <a href="#why">why</a>
* <a href="#other_features">other features</a>
* <a href="#security">security</a>
* <a href="#contact_and_license">contact and license</a>
* <a href="#_what">what</a>
* <a href="#_why">why</a>
* <a href="#_main_features">main features</a>
* <a href="#_support">support</a>
* <a href="#_security">security</a>
* <a href="#_contact_and_license">contact and license</a>
----
<a name="what"></a>
<a name="_what"></a>
### what
Gitolite allows a server to host many git repositories and provide access to
many developers, without having to give them real userids on or shell access
to the server. The essential magic in doing this is ssh's pubkey access and
the `authorized_keys` file, and the inspiration was an older program called
gitosis.
Gitolite lets you use a single user on a server to host many git repositories
and provide access to many developers, without having to give them real
userids on or shell access to the server. The essential magic in doing this
is ssh's pubkey access and the `authorized_keys` file, and the inspiration was
an older program called gitosis.
Gitolite can restrict who can read from (clone/fetch) or write to (push) a
repository. It can also restrict who can push to what branch or tag, which is
@ -55,7 +51,7 @@ requiring root permissions, and with no additional software than git itself
and perl. It also has several other neat features described below and
elsewhere in the [doc/][docs] directory.
<a name="why"></a>
<a name="_why"></a>
### why
@ -74,9 +70,9 @@ allow/disallow users access to repos.
But there are several disadvantages here:
* every user needs a userid and password on the server. This is usually a
killer...!
killer, especially in tightly controlled environments
* adding/removing access rights involves complex `usermod -G ...` mumblings
which most admins would rather not deal with, thanks to you-know-who
which most admins would rather not deal with
* *viewing* (aka auditing) the current set of permissions requires running
multiple commands to list directories and their permissions/ownerships,
users and their group memberships, and then correlating all these manually
@ -102,9 +98,9 @@ Gitolite does away with all this:
read-write access, not only at the repository level, but at the branch
level within repositories.
<a name="other_features"></a>
<a name="_main_features"></a>
### other features
### main features
The most important feature I needed was **per-branch permissions**. This is
pretty much mandatory in a corporate environment, and is almost the single
@ -136,7 +132,26 @@ detail somewhere in gitolite's [doc/][docs] subdirectory.
* specify repos using patterns (patterns may include creator's name)
* define powerful operations on the server side, even github-like forking
<a name="security"></a>
<a name="support"></a>
<a name="_support"></a>
### support
Most installation problems are caused by not knowing ssh. Take a look at this
[transcript][] to see how simple it actually is, if your server's ssh daemon
is behaving itself.
If I suspect your problem is an ssh issue, I will probably ignore it. Please
learn how [gitolite uses ssh][doc9gas] and then methodically go through the
[ssh trouble shooting][doc6sts] document. These two documents contain
everything I could possibly tell you. I have nothing to add.
Even for other topics, please look through at least the table of contents of
at least the numbered documents to see if your question is already answered,
before asking.
<a name="_security"></a>
### security
@ -158,11 +173,21 @@ details, looking for the word "security".
----
<a name="contact_and_license"></a>
<a name="_contact_and_license"></a>
### contact and license
Gitolite is released under GPL v2. See COPYING for details.
sitaramc@gmail.com
mailing list: gitolite@googlegroups.com
* author: sitaramc@gmail.com, sitaram@atc.tcs.com
* mailing list: gitolite@googlegroups.com
* list subscribe address : gitolite+subscribe@googlegroups.com
[transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd
[install]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd
[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd
[migr]: http://github.com/sitaramc/gitolite/blob/pu/doc/migrate.mkd
[docs]: http://github.com/sitaramc/gitolite/blob/pu/doc
[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite-and-ssh.mkd
[doc6sts]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd

184
doc/0-INSTALL.mkd → doc/1-INSTALL.mkd
View file

@ -2,40 +2,42 @@
In this document:
* <a href="#please_read_this_first">please read this first</a>
* <a href="#important_notes">important notes</a>
* <a href="#conventions_used">conventions used</a>
* <a href="#requirements">requirements</a>
* <a href="#client_side">client side</a>
* <a href="#server_side">server side</a>
* <a href="#installation_and_setup">installation and setup</a>
* <a href="#package_method_directly_on_the_server_using_RPM_DEB">(package method) directly on the server, using RPM/DEB</a>
* <a href="#root_method_directly_on_the_server_manually_with_root_access">(root method) directly on the server, manually, with root access</a>
* <a href="#non_root_method_directly_on_the_server_manually_without_root_access">(non-root method) directly on the server, manually, without root access</a>
* <a href="#from_client_method_install_from_the_client_to_the_server">(from-client method) install from the client to the server</a>
* <a href="#URLs_for_gitolite_managed_repos">URLs for gitolite-managed repos</a>
* <a href="#special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
* <a href="#package_method_and_root_method">package method and root method</a>
* <a href="#from_client_method">from-client method</a>
* <a href="#upgrading">upgrading</a>
* <a href="#uninstalling">uninstalling</a>
* <a href="#cleaning_out_a_botched_install">cleaning out a botched install</a>
* <a href="#uninstalling_gitolite_completely">uninstalling gitolite completely</a>
* <a href="#_please_read_this_first">please read this first</a>
* <a href="#_important_notes">important notes</a>
* <a href="#_conventions_used">conventions used</a>
* <a href="#_requirements">requirements</a>
* <a href="#_client_workstation">client/workstation</a>
* <a href="#_server">server</a>
* <a href="#_technical_skills">technical skills</a>
* <a href="#_installation_and_setup">installation and setup</a>
* <a href="#_install_methods_and_deciding_which_one_to_use">install methods and deciding which one to use</a>
* <a href="#_package_method_directly_on_the_server_using_RPM_DEB">(package method) directly on the server, using RPM/DEB</a>
* <a href="#_root_method_directly_on_the_server_manually_with_root_access">(root method) directly on the server, manually, with root access</a>
* <a href="#_non_root_method_directly_on_the_server_manually_without_root_access">(non-root method) directly on the server, manually, without root access</a>
* <a href="#_from_client_method_install_from_the_client_to_the_server">(from-client method) install from the client to the server</a>
* <a href="#_URLs_for_gitolite_managed_repos">URLs for gitolite-managed repos</a>
* <a href="#_special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
* <a href="#_package_method_and_root_method">package method and root method</a>
* <a href="#_from_client_method">from-client method</a>
* <a href="#_upgrading">upgrading</a>
* <a href="#_uninstalling">uninstalling</a>
* <a href="#_cleaning_out_a_botched_install">cleaning out a botched install</a>
* <a href="#_uninstalling_gitolite_completely">uninstalling gitolite completely</a>
----
<a name="please_read_this_first"></a>
<a name="_please_read_this_first"></a>
### please read this first
<a name="important_notes"></a>
<a name="_important_notes"></a>
#### important notes
Please make sure you understand the following points first.
* gitolite is somewhat unusual as far as "server" software goes -- every
userid on the server is a potential "gitolite host".
* gitolite runs as a single user on a server, and is invoked via ssh. Thus,
every user on the server is a potential "gitolite host".
* gitolite depends **heavily** on ssh pubkey (passwordless) access. Do not
assume you know all about ssh -- most people **don't**. If in doubt, use
@ -43,23 +45,45 @@ Please make sure you understand the following points first.
administration of gitolite.
To make matters worse, ssh problems in gitolite don't always look like ssh
problems. See [doc/6-ssh-troubleshooting.mkd][doc6] for help.
problems. See [doc/ssh-troubleshooting.mkd][doc6] for help.
<a name="conventions_used"></a>
A gitolite setup has:
* a server
* a "hosting user" on the server -- the userid under which gitolite runs.
You can have any number of "hosting users" on one server; in fact every
user can host their own gitolite instance
* an "admin user" -- the user who sets up gitolite and configures it
* the admin user's client or workstation, from which he does all his work
It is possible to have the server and the client be the same machine, and even
the admin user be also the hosting user, (i.e., `sitaram@server` can install
and administer a gitolite setup running under `sitaram@server`, a situation
that is common with some hosting services). It's actually fairly easy and
**safe** to do, **as long as you have password access to the server** for
emergency use. However, I will not be documenting it because (a) if you know
ssh you'll know how to extrapolate my instructions to do this and (b) if you
don't know ssh it'll be a nightmare to support you.
<a name="_conventions_used"></a>
#### conventions used
We assume the admin user is "sitaram", and his workstation is called "client".
The hosting user is "git", and the server is called "server". Substitute your
values as needed.
Throughout the documentation, we use "sitaram" as the admin user, and his
workstation is called "client". The hosting user is "git", and the server is
called "server". **Please substitute your values as needed**.
<a name="requirements"></a>
Also, we often say "the rc file". This means `~/.gitolite.rc` on the server.
And when we say the "access control rules", or "conf file", or "config file",
we mean `conf/gitolite.conf` on your gitolite-admin clone.
<a name="_requirements"></a>
#### requirements
<a name="client_side"></a>
<a name="_client_workstation"></a>
##### client side
##### client/workstation
* git version 1.6.2 or greater
* even msysgit on Windows is fine; please don't ask me for help if
@ -69,9 +93,9 @@ values as needed.
shell is needed
* again, msysgit on Windows is fine
<a name="server_side"></a>
<a name="_server"></a>
##### server side
##### server
* any Unix system with a posix compatible "sh".
* people using "csh" or derivatives please don't ask me for help -- tell
@ -82,11 +106,47 @@ values as needed.
* perl (but since git requires it anyway, you probably have it)
* openssh or any ssh that can understand the `authorized_keys` file format
<a name="installation_and_setup"></a>
<a name="_technical_skills"></a>
##### technical skills
* if you're installing gitolite, you're a "system admin", like it or not.
Ssh is therefore a necessary skill. Please take the time to learn at
least enough to get passwordless access working.
* you also need to be somewhat familiar with git itself. You cannot
administer a whole bunch of git repositories if you don't know the basics
of git.
* some familiarity with Unix and shells is probably required
* regular expressions are a big part of gitolite in many places but
familiarity is not necessary to do basic access control.
<a name="_installation_and_setup"></a>
### installation and setup
<a name="package_method_directly_on_the_server_using_RPM_DEB"></a>
<a name="methods"></a>
<a name="_install_methods_and_deciding_which_one_to_use"></a>
#### install methods and deciding which one to use
Gitolite has 4 install methods:
* **package method** if you have a gitolite RPM or a DEB available
* **root method** if you have root access to the server, and you plan to
have multiple "hosting users" on it
* **non-root method** if you don't have root access to the server, but you
do have at least one account with a password
* **from-client method** if you are not comfortable with public keys and
server side commands
Here's how you install using these 3 methods. Future upgrades are equally
easy -- the steps required for upgrading are marked "(U)".
<a name="_package_method_directly_on_the_server_using_RPM_DEB"></a>
#### (package method) directly on the server, using RPM/DEB
@ -100,7 +160,7 @@ values as needed.
* on the client, run `cd; git clone git@server:gitolite-admin`
<a name="root_method_directly_on_the_server_manually_with_root_access"></a>
<a name="_root_method_directly_on_the_server_manually_with_root_access"></a>
#### (root method) directly on the server, manually, with root access
@ -122,7 +182,7 @@ values as needed.
* on the client, run `cd; git clone git@server:gitolite-admin`
<a name="non_root_method_directly_on_the_server_manually_without_root_access"></a>
<a name="_non_root_method_directly_on_the_server_manually_without_root_access"></a>
#### (non-root method) directly on the server, manually, without root access
@ -151,22 +211,25 @@ server so that if you screw up the keys you can still get on, or be able to
* on the client, run `cd; git clone git@server:gitolite-admin`
<a name="from_client_method_install_from_the_client_to_the_server"></a>
<a name="fc"></a>
<a name="_from_client_method_install_from_the_client_to_the_server"></a>
#### (from-client method) install from the client to the server
This used to be the most common install method for a long time, and it is
still the one I use for most of my testing. The **main advantage** of this
method is that it **forces you** to solve the ssh pubkey problem **before**
attempting to install. Sadly, it also forces the admin to use a **different**
URL for gitolite repos than normal users, which seems to confuse a heck of a
lot of people who don't read the prominently displayed messages and/or the
documentation.
The advantage of this method is that it forces you to solve the ssh pubkey
problem **before** attempting to install. It works best if you have dedicated
userids, one on the server for installing gitolite, and one the client for
administering it.
This method is verbosely documented in [doc/7-install-transcript.mkd][doc7],
including *outputs* of the commands concerned.
Sadly, it also forces the admin to use a different URL to access gitolite
repos than normal users, which seems to confuse a heck of a lot of people who
don't read the prominently displayed messages and/or the documentation.
<a name="URLs_for_gitolite_managed_repos"></a>
This method is verbosely documented in this [transcript][], including
*outputs* of the commands concerned.
<a name="_URLs_for_gitolite_managed_repos"></a>
### URLs for gitolite-managed repos
@ -181,11 +244,11 @@ However, in the fourth ("from-client") method, the admin user needs a
different URL (`gitolite:reponame`) to gain access to the gitolite
repositories. Check [here][twokeys] for why.
<a name="special_cases_multiple_gitolite_servers"></a>
<a name="_special_cases_multiple_gitolite_servers"></a>
### special cases -- multiple gitolite servers
<a name="package_method_and_root_method"></a>
<a name="_package_method_and_root_method"></a>
#### package method and root method
@ -209,7 +272,7 @@ to have a command line on the server, so don't give them the passwords if you
don't need to -- the pubkey will allow them to be gitolite admins on their
domain, and that's quite enough for normal operations.
<a name="from_client_method"></a>
<a name="_from_client_method"></a>
#### from-client method
@ -229,7 +292,7 @@ have been created as respective clones. Or you can re-clone elsewhere:
cd ~/admin1; git clone gitolite_server_1:gitolite-admin.git
cd ~/admin2; git clone gitolite_server_2:gitolite-admin.git
<a name="upgrading"></a>
<a name="_upgrading"></a>
### upgrading
@ -244,11 +307,11 @@ also.
Also, remember that some new features may require additional settings in your
`~/.gitolite.rc` file.
<a name="uninstalling"></a>
<a name="_uninstalling"></a>
### uninstalling
<a name="cleaning_out_a_botched_install"></a>
<a name="_cleaning_out_a_botched_install"></a>
#### cleaning out a botched install
@ -266,18 +329,17 @@ here's how to clean the slate.
* remove `~/.gitolite`, `~/.gitolite.rc` and
`~/repositories/gitolite-admin.git`
<a name="uninstalling_gitolite_completely"></a>
<a name="_uninstalling_gitolite_completely"></a>
#### uninstalling gitolite completely
There's some duplication between this and the previous section, but
uninstalling gitolite is described in great detail in
[doc/9-uninstall.mkd][doc9unin]
[doc/uninstall.mkd][doc9unin]
----
[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd
[doc7]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd
[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-uninstall.mkd
[doc9ssh]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-ssh-tips.mkd
[twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd#why_two_keys_on_client
[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd
[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/uninstall.mkd
[twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd#twokeys
[transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd

84
doc/2-admin.mkd
View file

@ -1,38 +1,46 @@
# administering and running gitolite
In this document:
* <a href="#_please_read_this_first">please read this first</a>
* <a href="#_adding_users_and_repos">adding users and repos</a>
* <a href="#_other_features">other features</a>
* <a href="#_moving_pre_existing_repos_into_gitolite">moving pre-existing repos into gitolite</a>
* <a href="#_specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
* <a href="#_custom_hooks">custom hooks</a>
* <a href="#_hook_chaining">hook chaining</a>
* <a href="#_environment_variables_available_to_hooks">environment variables available to hooks</a>
* <a href="#_custom_git_config">custom git config</a>
----
<a name="_please_read_this_first"></a>
### please read this first
Unless you know what you're doing, do not do **anything** manually on the
server, like adding new repositories or users or changing the access control
rules. Things will break. For example, if you manually create a repo on the
server, it will not have the required "update" hook, without which there is no
access control for pushes.
Most normal (day-to-day) gitolite admin work is done by cloning the
gitolite-admin repo from the server to your workstation, making changes to the
clone, and pushing those changes back.
The installation steps in the previous section include the steps to do this
clone, so you should already have one on your workstation, in
`~/gitolite-admin`. You can of course clone it anywhere else you want and use
that clone.
Either way, make sure you `cd` into this clone first.
*Note*: some of the paths in this document use variable names. Just refer to
`~/.gitolite.rc` for the correct values for *your* installation.
In this document:
* <a href="#please_read_this_first">please read this first</a>
* <a href="#adding_users_and_repos">adding users and repos</a>
* <a href="#other_features">other features</a>
* <a href="#moving_pre_existing_repos_into_gitolite">moving pre-existing repos into gitolite</a>
* <a href="#specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
* <a href="#custom_hooks">custom hooks</a>
* <a href="#hook_chaining">hook chaining</a>
* <a href="#environment_variables_available_to_hooks">environment variables available to hooks</a>
* <a href="#custom_git_config">custom git config</a>
----
<a name="please_read_this_first"></a>
### please read this first
* ***do NOT add new repos manually***, unless you know how to add the
required hook as well. Without the hook, branch-level access control will
not work for that repo, which sorta defeats the idea of using gitolite :-)
* most normal (day-to-day) gitolite admin work is done by cloning the
gitolite-admin repo from the server to your workstation, making changes to
the clone, and pushing those changes back. The installation steps in
[doc/0-INSTALL.mkd][doc0] include the steps to do this clone if needed.
Once you've cloned it, you're ready to add users and repos.
<a name="adding_users_and_repos"></a>
<a name="_adding_users_and_repos"></a>
### adding users and repos
@ -57,11 +65,11 @@ Once you've cloned it, you're ready to add users and repos.
automatically be created (empty, but clonable) and users' access will be
updated as needed.
<a name="other_features"></a>
<a name="_other_features"></a>
### other features
<a name="moving_pre_existing_repos_into_gitolite"></a>
<a name="_moving_pre_existing_repos_into_gitolite"></a>
#### moving pre-existing repos into gitolite
@ -93,7 +101,7 @@ to take a bunch of existing repos and add them to gitolite:
`conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit,
push.
<a name="specifying_gitweb_and_daemon_access"></a>
<a name="_specifying_gitweb_and_daemon_access"></a>
#### specifying gitweb and daemon access
@ -102,10 +110,7 @@ like unauthenticated access of any kind to any repo!), but someone wanted it,
so here goes.
To make a repo or repo group accessible via "git daemon", just give read
permission to the special user "daemon". See the [faq, tips, etc][ss]
document for easy ways to specify access for multiple repositories.
[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd
permission to the special user "daemon".
There's a special user called "gitweb" also, which works the same way.
However, setting a description for the project also enables gitweb permissions
@ -131,7 +136,7 @@ The "compile" script will keep these files consistent with the config settings
-- this includes removing such settings/files if you remove "read" permissions
for the special usernames or remove the description line.
<a name="custom_hooks"></a>
<a name="_custom_hooks"></a>
#### custom hooks
@ -150,7 +155,7 @@ implements all the branch-level permissions in gitolite. If you fiddle with
the hooks directory, please make sure you do not mess with this file
accidentally, or all your fancy per-branch permissions will stop working.**
<a name="hook_chaining"></a>
<a name="_hook_chaining"></a>
#### hook chaining
@ -173,7 +178,7 @@ Finally, these names (`update.secondary` and `post-update.secondary`) are
merely the defaults. You can change them to anything you want; look in
conf/example.gitolite.rc for details.
<a name="environment_variables_available_to_hooks"></a>
<a name="_environment_variables_available_to_hooks"></a>
#### environment variables available to hooks
@ -189,7 +194,7 @@ The following variables are also set, but are generally less useful:
* `GL_BINDIR` -- where all the binaries live
* `GL_ADMINDIR` -- common directory for many gitolite things
<a name="custom_git_config"></a>
<a name="_custom_git_config"></a>
#### custom git config
@ -213,6 +218,5 @@ basic forms of the "git config" command:
It does not (currently) support other options like `--add`, the `value_regex`,
etc.
[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key

177
doc/3-faq-tips-etc.mkd
View file

@ -2,48 +2,48 @@
In this document:
* <a href="#common_errors_and_mistakes">common errors and mistakes</a>
* <a href="#git_version_dependency">git version dependency</a>
* <a href="#other_errors_warnings_notes_">other errors, warnings, notes...</a>
* <a href="#cloning_an_empty_repo">cloning an empty repo</a>
* <a href="#all_syntax_for_repos">`@all` syntax for repos</a>
* <a href="#umask_setting">umask setting</a>
* <a href="#getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
* <a href="#features">features</a>
* <a href="#syntax_and_normal_usage">syntax and normal usage</a>
* <a href="#simpler_syntax">simpler syntax</a>
* <a href="#one_user_many_keys">one user, many keys</a>
* <a href="#security_access_control_and_auditing">security, access control, and auditing</a>
* <a href="#two_levels_of_access_rights_checking">two levels of access rights checking</a>
* <a href="#better_logging">better logging</a>
* <a href="#exclude_or_deny_rules">"exclude" (or "deny") rules</a>
* <a href="#separating_delete_and_rewind_rights">separating delete and rewind rights</a>
* <a href="#separating_create_and_push_rights">separating create and push rights</a>
* <a href="#file_dir_NAME_based_restrictions">file/dir NAME based restrictions</a>
* <a href="#delegating_parts_of_the_config_file">delegating parts of the config file</a>
* <a href="#convenience_features">convenience features</a>
* <a href="#what_repos_do_I_have_access_to_">what repos do I have access to?</a>
* <a href="#including_config_lines_from_other_files">including config lines from other files</a>
* <a href="#support_for_git_installed_outside_default_PATH">support for git installed outside default PATH</a>
* <a href="#personal_branches">"personal" branches</a>
* <a href="#custom_hooks_and_custom_git_config">custom hooks and custom git config</a>
* <a href="#bypassing_gitolite">bypassing gitolite</a>
* <a href="#INconvenience_features">INconvenience features</a>
* <a href="#deleting_a_repo">deleting a repo</a>
* <a href="#helping_with_gitweb">helping with gitweb</a>
* <a href="#easier_to_specify_gitweb_description_and_gitweb_daemon_access">easier to specify gitweb "description" and gitweb/daemon access</a>
* <a href="#easier_to_link_gitweb_authorisation_with_gitolite">easier to link gitweb authorisation with gitolite</a>
* <a href="#advanced_features">advanced features</a>
* <a href="#repos_named_with_wildcards">repos named with wildcards</a>
* <a href="#admin_defined_commands">admin defined commands</a>
* <a href="#access_control_for_external_commands">access control for external commands</a>
* <a href="#svnserve">svnserve</a>
* <a href="#design_choices">design choices</a>
* <a href="#keeping_the_parser_and_the_access_control_separate">keeping the parser and the access control separate</a>
* <a href="#_common_errors_and_mistakes">common errors and mistakes</a>
* <a href="#_git_version_dependency">git version dependency</a>
* <a href="#_other_errors_warnings_notes_">other errors, warnings, notes...</a>
* <a href="#_cloning_an_empty_repo">cloning an empty repo</a>
* <a href="#_all_syntax_for_repos">`@all` syntax for repos</a>
* <a href="#_umask_setting">umask setting</a>
* <a href="#_getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
* <a href="#_features">features</a>
* <a href="#_syntax_and_normal_usage">syntax and normal usage</a>
* <a href="#_simpler_syntax">simpler syntax</a>
* <a href="#_one_user_many_keys">one user, many keys</a>
* <a href="#_security_access_control_and_auditing">security, access control, and auditing</a>
* <a href="#_two_levels_of_access_rights_checking">two levels of access rights checking</a>
* <a href="#_better_logging">better logging</a>
* <a href="#_exclude_or_deny_rules">"exclude" (or "deny") rules</a>
* <a href="#_separating_delete_and_rewind_rights">separating delete and rewind rights</a>
* <a href="#_separating_create_and_push_rights">separating create and push rights</a>
* <a href="#_file_dir_NAME_based_restrictions">file/dir NAME based restrictions</a>
* <a href="#_delegating_parts_of_the_config_file">delegating parts of the config file</a>
* <a href="#_convenience_features">convenience features</a>
* <a href="#_what_repos_do_I_have_access_to_">what repos do I have access to?</a>
* <a href="#_including_config_lines_from_other_files">including config lines from other files</a>
* <a href="#_support_for_git_installed_outside_default_PATH">support for git installed outside default PATH</a>
* <a href="#_personal_branches">"personal" branches</a>
* <a href="#_custom_hooks_and_custom_git_config">custom hooks and custom git config</a>
* <a href="#_bypassing_gitolite">bypassing gitolite</a>
* <a href="#_INconvenience_features">INconvenience features</a>
* <a href="#_deleting_a_repo">deleting a repo</a>
* <a href="#_helping_with_gitweb">helping with gitweb</a>
* <a href="#_easier_to_specify_gitweb_description_and_gitweb_daemon_access">easier to specify gitweb "description" and gitweb/daemon access</a>
* <a href="#_easier_to_link_gitweb_authorisation_with_gitolite">easier to link gitweb authorisation with gitolite</a>
* <a href="#_advanced_features">advanced features</a>
* <a href="#_repos_named_with_wildcards">repos named with wildcards</a>
* <a href="#_admin_defined_commands">admin defined commands</a>
* <a href="#_access_control_for_external_commands">access control for external commands</a>
* <a href="#_svnserve">svnserve</a>
* <a href="#_design_choices">design choices</a>
* <a href="#_keeping_the_parser_and_the_access_control_separate">keeping the parser and the access control separate</a>
----
<a name="common_errors_and_mistakes"></a>
<a name="_common_errors_and_mistakes"></a>
### common errors and mistakes
@ -65,19 +65,19 @@ In this document:
In other words, you used a key that completely bypassed gitolite and went
straight to the shell to do the clone.
Please see doc/6-ssh-troubleshooting.mkd for what all this means.
Please see doc/ssh-troubleshooting.mkd for what all this means.
<a name="git_version_dependency"></a>
<a name="_git_version_dependency"></a>
### git version dependency
Gitolite (on the server) now refuses to run if git is not at least 1.6.2.
<a name="other_errors_warnings_notes_"></a>
<a name="_other_errors_warnings_notes_"></a>
### other errors, warnings, notes...
<a name="cloning_an_empty_repo"></a>
<a name="_cloning_an_empty_repo"></a>
#### cloning an empty repo
@ -90,7 +90,7 @@ end hung up unexpectedly`. However, you can ignore this, since it doesn't
seem to hurt anything. [Update 2009-09-14; this has been fixed in git
1.6.4.3]
<a name="all_syntax_for_repos"></a>
<a name="_all_syntax_for_repos"></a>
#### `@all` syntax for repos
@ -102,14 +102,14 @@ There *is* a way to use the `@all` syntax for repos also, as described in
access, we do not support this.
* don't try giving `@all` users some permission for `@all` repos
<a name="umask_setting"></a>
<a name="_umask_setting"></a>
#### umask setting
Gitweb not able to read your repos? You can change the umask for newly
created repos to something more relaxed -- see the `~/.gitolite.rc` file
<a name="getting_a_tar_file_from_a_clone"></a>
<a name="_getting_a_tar_file_from_a_clone"></a>
### getting a tar file from a clone
@ -125,7 +125,7 @@ plain "git archive", because the Makefile adds a file called
make master.tar
# or maybe "make pu.tar"
<a name="features"></a>
<a name="_features"></a>
### features
@ -133,11 +133,11 @@ Apart from the big ones listed in the top level README, and subjective ones
like "better config file format", gitolite has evolved to have many useful
features than the original goal of branch-level access control.
<a name="syntax_and_normal_usage"></a>
<a name="_syntax_and_normal_usage"></a>
#### syntax and normal usage
<a name="simpler_syntax"></a>
<a name="_simpler_syntax"></a>
##### simpler syntax
@ -182,7 +182,9 @@ do not worry that this causes some duplication or inefficiency. It doesn't
See the "specify gitweb/daemon access" section below for one more example.
<a name="one_user_many_keys"></a>
<a name="multikeys"></a>
<a name="_one_user_many_keys"></a>
##### one user, many keys
@ -227,11 +229,11 @@ corresponding derived usernames (which is what goes into the
sitaramc@gmail.com@laptop.pub sitaramc@gmail.com
sitaramc@gmail.com@desktop.pub sitaramc@gmail.com
<a name="security_access_control_and_auditing"></a>
<a name="_security_access_control_and_auditing"></a>
#### security, access control, and auditing
<a name="two_levels_of_access_rights_checking"></a>
<a name="_two_levels_of_access_rights_checking"></a>
##### two levels of access rights checking
@ -267,7 +269,7 @@ any of the refexes match, the push succeeds. If none of them match, it fails.
Gitolite also allows "exclude" or "deny" rules. See later in this document
for details.
<a name="better_logging"></a>
<a name="_better_logging"></a>
##### better logging
@ -295,7 +297,7 @@ The other parts of the log line are the name of the repo, the refname being
updated, the user updating it, and the refex pattern (from the config file)
that matched, in case you need to debug the config file itself.
<a name="exclude_or_deny_rules"></a>
<a name="_exclude_or_deny_rules"></a>
##### "exclude" (or "deny") rules
@ -346,7 +348,7 @@ And here's how it works:
before the third one, and it has a `-` as the permission, so the push
fails
<a name="separating_delete_and_rewind_rights"></a>
<a name="_separating_delete_and_rewind_rights"></a>
##### separating delete and rewind rights
@ -386,9 +388,7 @@ message when you push, a non-existant user.
Note 3: you can combine this with the "create a branch" permissions described
in the next section, as the example line in conf/example.conf shows.
[sdrr]: http://groups.google.com/group/gitolite/browse_thread/thread/9f2b4358ce406d4c#
<a name="separating_create_and_push_rights"></a>
<a name="_separating_create_and_push_rights"></a>
##### separating create and push rights
@ -406,7 +406,7 @@ Briefly:
Note: you can combine this with the "delete a branch" permissions described in
the previous section, as the example line in conf/example.conf shows.
<a name="file_dir_NAME_based_restrictions"></a>
<a name="_file_dir_NAME_based_restrictions"></a>
##### file/dir NAME based restrictions
@ -417,20 +417,18 @@ changed, treating each filename as a "ref" to be matched.
Please see `conf/example.conf` for syntax and examples.
<a name="delegating_parts_of_the_config_file"></a>
<a name="_delegating_parts_of_the_config_file"></a>
##### delegating parts of the config file
You can now split up the config file and delegate the authority to specify
access control for their own pieces. See
[doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
for details.
access control for their own pieces. See [delegation][] for details.
<a name="convenience_features"></a>
<a name="_convenience_features"></a>
#### convenience features
<a name="what_repos_do_I_have_access_to_"></a>
<a name="_what_repos_do_I_have_access_to_"></a>
##### what repos do I have access to?
@ -441,15 +439,13 @@ etc. You'd just like a simple way to know what repos you have access to.
Gitolite provides two commands (`info` and `expand`) to help you find this
information; please check [doc/report-output.mkd][repout] for details.
[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
<a name="including_config_lines_from_other_files"></a>
<a name="_including_config_lines_from_other_files"></a>
##### including config lines from other files
See the entry under "INCLUDE SOME OTHER FILE" in `conf/example.conf`.
<a name="support_for_git_installed_outside_default_PATH"></a>
<a name="_support_for_git_installed_outside_default_PATH"></a>
##### support for git installed outside default PATH
@ -483,7 +479,7 @@ the full PATH in the rc file, like so:
$ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}";
<a name="personal_branches"></a>
<a name="_personal_branches"></a>
##### "personal" branches
@ -507,7 +503,7 @@ important thing is that the "branch" name should contain `/USER/` (including
the slashes). At runtime this will match whoever is the current user. Access
is still determined by the right hand side of course.
<a name="custom_hooks_and_custom_git_config"></a>
<a name="_custom_hooks_and_custom_git_config"></a>
##### custom hooks and custom git config
@ -515,7 +511,7 @@ You can specify hooks that you want to propagate to all repos, as well as
per-repo "gitconfig" settings. Please see `doc/2-admin.mkd` and
`conf/example.conf` for details.
<a name="bypassing_gitolite"></a>
<a name="_bypassing_gitolite"></a>
##### bypassing gitolite
@ -538,11 +534,11 @@ to set that variable permanently, preferring this mode instead:
GL_BYPASS_UPDATE_HOOK=1 git push
<a name="INconvenience_features"></a>
<a name="_INconvenience_features"></a>
#### INconvenience features
<a name="deleting_a_repo"></a>
<a name="_deleting_a_repo"></a>
##### deleting a repo
@ -550,8 +546,6 @@ By design, there is no code in gitolite to *delete* a repo if the repo was
specified by name in the config file. (Wildcard repos *can* be deleted by the
user; see [here][rmrepo] for details).
[rmrepo]: http://github.com/sitaramc/gitolite/blob/pu/doc/admin-defined-commands.mkd#rmrepo
If you *do* want to permanently delete a *non*-wildcard repo, here's what you
do:
@ -561,7 +555,7 @@ do:
* *then* remove the repo from `~/repositories` on the server (or whatever
you set `$GL_REPO_BASE` to in the `~/.gitolite.rc`)
<a name="helping_with_gitweb"></a>
<a name="_helping_with_gitweb"></a>
#### helping with gitweb
@ -569,7 +563,9 @@ Although gitweb is a completely separate program, gitolite can do quite a
lot to help you manage gitweb access as well; once the initial setup is
complete, you can do it all from within the gitolite config file!
<a name="easier_to_specify_gitweb_description_and_gitweb_daemon_access"></a>
<a name="gwd"></a>
<a name="_easier_to_specify_gitweb_description_and_gitweb_daemon_access"></a>
##### easier to specify gitweb "description" and gitweb/daemon access
@ -618,7 +614,7 @@ Here's an example, using really short reponames because I'm lazy:
repo r2
# ...and so on...
<a name="easier_to_link_gitweb_authorisation_with_gitolite"></a>
<a name="_easier_to_link_gitweb_authorisation_with_gitolite"></a>
##### easier to link gitweb authorisation with gitolite
@ -654,24 +650,24 @@ Gitweb allows you to specify a subroutine to decide on access. We use that
feature and tie it to gitolite. Configuration example can be found in
`contrib/gitweb/`.
<a name="advanced_features"></a>
<a name="_advanced_features"></a>
#### advanced features
<a name="repos_named_with_wildcards"></a>
<a name="_repos_named_with_wildcards"></a>
##### repos named with wildcards
Please see `doc/4-wildcard-repositories.mkd` for all the details.
Please see `doc/wildcard-repositories.mkd` for all the details.
<a name="admin_defined_commands"></a>
<a name="_admin_defined_commands"></a>
##### admin defined commands
This requires the wildcards feature to be enabled, but is then an extremely
powerful feature. See `doc/admin-defined-commands.mkd`.
<a name="access_control_for_external_commands"></a>
<a name="_access_control_for_external_commands"></a>
##### access control for external commands
@ -681,7 +677,7 @@ server-side command that contains enough information to make an access control
decision.
Note that this is incompatible with giving people shell access as described in
`doc/6-ssh-troubleshooting.mkd` -- people who have shell access are not
`doc/ssh-troubleshooting.mkd` -- people who have shell access are not
subject to this mechanism (it wouldn't make sense to try and control someone
who has shell access anyway).
@ -695,7 +691,7 @@ Commands implemented so far are:
* svnserve (see next section for a brief description; this has been
contributed by Simon and Vladimir)
<a name="svnserve"></a>
<a name="_svnserve"></a>
###### svnserve
@ -707,11 +703,11 @@ system. Assuming you installed gitolite to the same user as the one you used
for SVN, SVN connectivity will be retained, and users will be able to use
both SVN and git using the same SSH configuration.
<a name="design_choices"></a>
<a name="_design_choices"></a>
### design choices
<a name="keeping_the_parser_and_the_access_control_separate"></a>
<a name="_keeping_the_parser_and_the_access_control_separate"></a>
#### keeping the parser and the access control separate
@ -732,3 +728,8 @@ have to be first "compiled", and the access control programs use this
If you choose the "easy install" method, all this is quite transparent to you
anyway. If you cannot use the easy install and must install manually, I have
clear instructions on how to set it up.
[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
[sdrr]: http://groups.google.com/group/gitolite/browse_thread/thread/9f2b4358ce406d4c#
[delegation]: http://github.com/sitaramc/gitolite/blob/pu/doc/delegation.mkd
[rmrepo]: http://github.com/sitaramc/gitolite/blob/pu/doc/admin-defined-commands.mkd#rmrepo

43
doc/admin-defined-commands.mkd
View file

@ -11,18 +11,18 @@ There may be other such **WARNING** sections below. **Read all of them**.
In this document:
* <a href="#background">background</a>
* <a href="#setting_it_up">setting it up</a>
* <a href="#anatomy_of_a_command">anatomy of a command</a>
* <a href="#example_uses_and_sample_commands_in_contrib">example uses and sample commands in contrib</a>
* <a href="#fork">fork</a>
* <a href="#rmrepo">rmrepo</a>
* <a href="#enable_disable_push_access_temporarily">enable/disable push access temporarily</a>
* <a href="#bonus_restricted_admin">(bonus) restricted admin</a>
* <a href="#_background">background</a>
* <a href="#_setting_it_up">setting it up</a>
* <a href="#_anatomy_of_a_command">anatomy of a command</a>
* <a href="#_example_uses_and_sample_commands_in_contrib">example uses and sample commands in contrib</a>
* <a href="#_fork">fork</a>
* <a href="#_rmrepo">rmrepo</a>
* <a href="#_enable_disable_push_access_temporarily">enable/disable push access temporarily</a>
* <a href="#_bonus_restricted_admin">(bonus) restricted admin</a>
----
<a name="background"></a>
<a name="_background"></a>
### background
@ -36,9 +36,6 @@ resisted the urge to point him to [this][xkcd224], told him that's a great
idea and he should go for it, mentally blessing him for letting me off the
hook on coding it ;-) [Laziness][lazy] *is* the first virtue you know!
[xkcd224]: http://xkcd.com/224/
[lazy]: http://c2.com/cgi/wiki?LazinessImpatienceHubris
And that was that. For a couple of days.
Soon, though, I realised that there could be a pretty big bonus in this for
@ -47,13 +44,11 @@ on "restricted admin" for what's really exciting about this for *me*.
----
It may be a good idea to read [doc/4-wildcard-repositories.mkd][wild] before
It may be a good idea to read [doc/wildcard-repositories.mkd][wild] before
you continue here though, because most of the uses of this feature also need
wildcard repos. (This also means you must set `$GL_WILDREPOS` to "1" in the
rc file).
[wild]: http://github.com/sitaramc/gitolite/blob/pu/doc/4-wildcard-repositories.mkd
The wildcard repo feature is a way to create repositories matching a pattern
(even if it as simple as `personal/CREATOR/.+`), and a way to specify two
categories of permissions for each such user-created repo.
@ -62,7 +57,7 @@ What we want now is more than that, as you'll see in the examples below. And
I'm sure if you think of more uses you'll send them to me as "contrib"
entries, right?
<a name="setting_it_up"></a>
<a name="_setting_it_up"></a>
### setting it up
@ -82,7 +77,7 @@ to inadvertently *hide* some of the "official" commands (like "info",
executable files with those names in this directory. So don't do that -- you
have been warned!**
<a name="anatomy_of_a_command"></a>
<a name="_anatomy_of_a_command"></a>
### anatomy of a command
@ -137,11 +132,11 @@ convenient. See any of the other samples for how to use it.
If you don't like this, roll your own. If you don't like bash, do the eqvt in
your language of choice.
<a name="example_uses_and_sample_commands_in_contrib"></a>
<a name="_example_uses_and_sample_commands_in_contrib"></a>
### example uses and sample commands in contrib
<a name="fork"></a>
<a name="_fork"></a>
#### fork
@ -169,6 +164,8 @@ or some such incantation.
<a name="rmrepo"></a>
<a name="_rmrepo"></a>
#### rmrepo
This is one thing that you really could not do before this setup was created.
@ -179,7 +176,7 @@ Use it like this:
The script checks to make sure that the repo being deleted was *created* by
the user invoking it.
<a name="enable_disable_push_access_temporarily"></a>
<a name="_enable_disable_push_access_temporarily"></a>
#### enable/disable push access temporarily
@ -217,7 +214,7 @@ in doc/2. You need code like this in `update.secondary` (don't forget to
exit 0
<a name="bonus_restricted_admin"></a>
<a name="_bonus_restricted_admin"></a>
#### (bonus) restricted admin
@ -239,3 +236,7 @@ script to proceed.
[Note that this particular use does not require `$GL_WILDREPOS` to be enabled,
because it's not using any wildcard repos].
[xkcd224]: http://xkcd.com/224/
[lazy]: http://c2.com/cgi/wiki?LazinessImpatienceHubris
[wild]: http://github.com/sitaramc/gitolite/blob/pu/doc/wildcard-repositories.mkd

28
doc/big-config.mkd
View file

@ -2,13 +2,13 @@
In this document:
* <a href="#when_why_do_we_need_it_">when/why do we need it?</a>
* <a href="#how_do_we_use_it_">how do we use it?</a>
* <a href="#other_optimisations">other optimisations</a>
* <a href="#what_are_the_downsides_">what are the downsides?</a>
* <a href="#extra_coolness_usergroups_and_LDAP_similar_tools">(extra coolness) usergroups and LDAP/similar tools</a>
* <a href="#_when_why_do_we_need_it_">when/why do we need it?</a>
* <a href="#_how_do_we_use_it_">how do we use it?</a>
* <a href="#_other_optimisations">other optimisations</a>
* <a href="#_what_are_the_downsides_">what are the downsides?</a>
* <a href="#_extra_coolness_usergroups_and_LDAP_similar_tools">(extra coolness) usergroups and LDAP/similar tools</a>
<a name="when_why_do_we_need_it_"></a>
<a name="_when_why_do_we_need_it_"></a>
### when/why do we need it?
@ -95,7 +95,7 @@ Phew!
You can imagine what that does when you have 10,000 users and 10,000 repos.
Let's just say it's not pretty :)
<a name="how_do_we_use_it_"></a>
<a name="_how_do_we_use_it_"></a>
### how do we use it?
@ -143,7 +143,7 @@ looks like this:
That's a lot smaller, and allows orders of magintude more repos and groups to
be supported.
<a name="other_optimisations"></a>
<a name="_other_optimisations"></a>
### other optimisations
@ -158,8 +158,8 @@ first one):
`GL_NO_DAEMON_NO_GITWEB` is a very useful optimisation that you *must* enable
if you *do* have a large number of repositories, and do *not* use gitolite's
support for gitweb or git-daemon access (see "[easier to specify gitweb
description and gitweb/daemon access][gw]" for details). This will save a lot
of time when you push the gitolite-admin repo with changes. This variable
description and gitweb/daemon access][gwd]" for details). This will save a
lot of time when you push the gitolite-admin repo with changes. This variable
also control whether "git config" lines (such as `config hooks.emailprefix =
"[gitolite]"`) will be processed or not.
@ -176,9 +176,7 @@ Also note that using all 3 of the `GL_NO_*` variables will result in
*everything* after the config compile being skipped. In other words, gitolite
is being used **only** for its access control language.
[gw]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gitweb
<a name="what_are_the_downsides_"></a>
<a name="_what_are_the_downsides_"></a>
### what are the downsides?
@ -192,7 +190,7 @@ subset of the allowed @fragname, which would work normally, do not work now).
(If you didn't understand all that, you're probably not using delegation, so
feel free to ignore it!)
<a name="extra_coolness_usergroups_and_LDAP_similar_tools"></a>
<a name="_extra_coolness_usergroups_and_LDAP_similar_tools"></a>
### (extra coolness) usergroups and LDAP/similar tools
@ -238,3 +236,5 @@ specified:
@foo = alice
@bar = alice
[gwd]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd

29
doc/5-delegation.mkd → doc/delegation.mkd
View file

@ -6,25 +6,22 @@
In this document:
* <a href="#lots_of_repos_lots_of_users">lots of repos, lots of users</a>
* <a href="#splitting_up_the_set_of_repos_into_groups">splitting up the set of repos into groups</a>
* <a href="#delegating_ownership_of_groups_of_repos">delegating ownership of groups of repos</a>
* <a href="#security_philosophy_note">security/philosophy note</a>
* <a href="#_lots_of_repos_lots_of_users">lots of repos, lots of users</a>
* <a href="#_splitting_up_the_set_of_repos_into_groups">splitting up the set of repos into groups</a>
* <a href="#_delegating_ownership_of_groups_of_repos">delegating ownership of groups of repos</a>
* <a href="#_security_philosophy_note">security/philosophy note</a>
----
<a name="lots_of_repos_lots_of_users"></a>
<a name="_lots_of_repos_lots_of_users"></a>
### lots of repos, lots of users
Gitolite tries to make it easy to manage access to lots of users and repos,
exploiting commonalities wherever possible. (The example in [this
section][ss] should give you an idea). As you can see, it lets you specify
bits and pieces of the access control separately -- i.e., *all* the access
specs for a certain repo need not be together; they can be scattered, which
makes it easier to manage the sort of slice and dice needed in that example.
[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#simpler_syntax
exploiting commonalities wherever possible. It lets you specify bits and
pieces of the access control separately -- i.e., *all* the access specs for a
certain repo need not be together; they can be scattered, which makes it
easier to manage the sort of slice and dice needed in that example.
But eventually the config file will become too big. If you let only one
person have control, he could become a bottleneck. If you give it to multiple
@ -47,7 +44,7 @@ access control rules for a set of repos they have been given authority for.
It's easier to show how it all works with an example instead of long
descriptions.
<a name="splitting_up_the_set_of_repos_into_groups"></a>
<a name="_splitting_up_the_set_of_repos_into_groups"></a>
### splitting up the set of repos into groups
@ -63,7 +60,7 @@ or repos, same syntax). So the basic idea is that the main config file
# any other config as usual, including access control lines for any of the
# above projects or groups
<a name="delegating_ownership_of_groups_of_repos"></a>
<a name="_delegating_ownership_of_groups_of_repos"></a>
### delegating ownership of groups of repos
@ -117,7 +114,7 @@ to the bottom of the main file.
----
<a name="security_philosophy_note"></a>
<a name="_security_philosophy_note"></a>
### security/philosophy note
@ -136,4 +133,4 @@ If you feel the need to delegate even that, please just go the whole hog and
give them separate gitolite instances! It's pretty easy to setup the
*software* itself system-wide, so that many users can use it without all the
"easy install" fuss. See the "system install / user setup" section in
doc/0-INSTALL.mkd for details.
doc/1-INSTALL.mkd for details.

16
doc/9-gitolite-and-ssh.mkd → doc/gitolite-and-ssh.mkd
View file

@ -13,14 +13,14 @@ blaming ***git/gitolite*** for whatever is going wrong with your setup :-)
In this document:
* <a href="#ssh_basics">ssh basics</a>
* <a href="#how_does_gitolite_use_all_this_ssh_magic_">how does gitolite use all this ssh magic?</a>
* <a href="#restricting_shell_access_distinguishing_one_user_from_another">restricting shell access/distinguishing one user from another</a>
* <a href="#restricting_branch_level_actions">restricting branch level actions</a>
* <a href="#_ssh_basics">ssh basics</a>
* <a href="#_how_does_gitolite_use_all_this_ssh_magic_">how does gitolite use all this ssh magic?</a>
* <a href="#_restricting_shell_access_distinguishing_one_user_from_another">restricting shell access/distinguishing one user from another</a>
* <a href="#_restricting_branch_level_actions">restricting branch level actions</a>
----
<a name="ssh_basics"></a>
<a name="_ssh_basics"></a>
### ssh basics
@ -88,7 +88,7 @@ from somewhere, or maybe buy the OReilly ssh book.
**This is the backbone of what makes gitolite work; please make sure you
understand this**
<a name="how_does_gitolite_use_all_this_ssh_magic_"></a>
<a name="_how_does_gitolite_use_all_this_ssh_magic_"></a>
### how does gitolite use all this ssh magic?
@ -98,7 +98,7 @@ These are two different questions you ought to be having by now:
logging in as the same remote user "git"
* how does it restrict what I can do within a repository
<a name="restricting_shell_access_distinguishing_one_user_from_another"></a>
<a name="_restricting_shell_access_distinguishing_one_user_from_another"></a>
#### restricting shell access/distinguishing one user from another
@ -131,7 +131,7 @@ at its config file, and either allows or rejects the request.
But this cannot differentiate between different branches within a repo; that
has to be done separately.
<a name="restricting_branch_level_actions"></a>
<a name="_restricting_branch_level_actions"></a>
#### restricting branch level actions

40
doc/hook-propagation.mkd
View file

@ -6,17 +6,17 @@ put them, what takes precedence. I'll try and set out the logic here.
In this document:
* <a href="#hooks_used_by_gitolite">hooks used by gitolite</a>
* <a href="#where_do_I_the_admin_put_the_hooks_">**where** do I (the admin) put the hooks?</a>
* <a href="#the_from_client_method">the "from-client" method</a>
* <a href="#the_other_3_methods">the other 3 methods</a>
* <a href="#the_GL_PACKAGE_HOOKS_directory">the `GL_PACKAGE_HOOKS` directory</a>
* <a href="#the_HOME_gitolite_directory">the `$HOME/.gitolite` directory</a>
* <a href="#why_two_places_">why two places?</a>
* <a href="#special_case_the_non_root_method">special case: the "non-root" method</a>
* <a href="#when_do_hooks_propagate_">**when** do hooks propagate?</a>
* <a href="#_hooks_used_by_gitolite">hooks used by gitolite</a>
* <a href="#_where_do_I_the_admin_put_the_hooks_">**where** do I (the admin) put the hooks?</a>
* <a href="#_the_from_client_method">the "from-client" method</a>
* <a href="#_the_other_3_methods">the other 3 methods</a>
* <a href="#_the_GL_PACKAGE_HOOKS_directory">the `GL_PACKAGE_HOOKS` directory</a>
* <a href="#_the_HOME_gitolite_directory">the `$HOME/.gitolite` directory</a>
* <a href="#_why_two_places_">why two places?</a>
* <a href="#_special_case_the_non_root_method">special case: the "non-root" method</a>
* <a href="#_when_do_hooks_propagate_">**when** do hooks propagate?</a>
<a name="hooks_used_by_gitolite"></a>
<a name="_hooks_used_by_gitolite"></a>
### hooks used by gitolite
@ -32,7 +32,7 @@ In addition there is a "sentinel file" -- an empty file called
The final objective of all this is that each repo's `hooks/` directory should
get all the hooks that it is meant to get.
<a name="where_do_I_the_admin_put_the_hooks_"></a>
<a name="_where_do_I_the_admin_put_the_hooks_"></a>
### **where** do I (the admin) put the hooks?
@ -44,9 +44,9 @@ Now we'll discuss the locations of these `hooks/common` and
`hooks/gitolite-admin` directories. This depends on which install method you
used.
(Please refer to [doc/0-INSTALL.mkd][0inst] for what these "methods" are).
(Please refer to [doc/1-INSTALL.mkd][0inst] for what these "methods" are).
<a name="the_from_client_method"></a>
<a name="_the_from_client_method"></a>
#### the "from-client" method
@ -57,11 +57,11 @@ gitolite clone on the client side. This is where you run
method; skip to the next section ("when do hooks propagate") if you installed
using the "from-client" method.
<a name="the_other_3_methods"></a>
<a name="_the_other_3_methods"></a>
#### the other 3 methods
<a name="the_GL_PACKAGE_HOOKS_directory"></a>
<a name="_the_GL_PACKAGE_HOOKS_directory"></a>
##### the `GL_PACKAGE_HOOKS` directory
@ -80,7 +80,7 @@ process does the equivalent of `gl-system-install`.
So now we know there's a location called `$GL_PACKAGE_HOOKS` where you can
place your hooks.
<a name="the_HOME_gitolite_directory"></a>
<a name="_the_HOME_gitolite_directory"></a>
##### the `$HOME/.gitolite` directory
@ -90,7 +90,7 @@ directory, which also contains a `hooks/` directory.
So now there are two places you can put your hooks, apparently.
<a name="why_two_places_"></a>
<a name="_why_two_places_"></a>
#### why two places?
@ -116,7 +116,7 @@ get copied to `$HOME/.gitolite/hooks` when you "install". I need to fix and
thoroughly test this later; for now, just ignore the extra files you see in
there; they're harmless/redundant (TODO)]
<a name="special_case_the_non_root_method"></a>
<a name="_special_case_the_non_root_method"></a>
#### special case: the "non-root" method
@ -127,7 +127,7 @@ existed to cater to the "package" and "root" methods. In this method, the
*strongly* suggest putting them in `$GL_PACKAGE_HOOKS` and ignoring
`$HOME/.gitolite` completely.
<a name="when_do_hooks_propagate_"></a>
<a name="_when_do_hooks_propagate_"></a>
### **when** do hooks propagate?
@ -171,5 +171,5 @@ For people who do not want certain hooks to run for certain repos, one simple
solution that will work right now is to check the value of `$GL_REPO` at the
start of the hook, and `exit 0` based on what it contains/matches.
[0inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
[0inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd

34
doc/7-install-transcript.mkd → doc/install-transcript.mkd
View file

@ -2,18 +2,18 @@
In this document:
* <a href="#about_this_document">about this document</a>
* <a href="#create_userids_on_server_and_client_optional_">create userids on server and client (optional)</a>
* <a href="#get_pubkey_access_from_client_to_server">get pubkey access from client to server</a>
* <a href="#get_gitolite_source">get gitolite source</a>
* <a href="#install_gitolite">install gitolite</a>
* <a href="#VERY_IMPORTANT_">VERY IMPORTANT...</a>
* <a href="#examine_what_you_have">examine what you have</a>
* <a href="#emergency_password_access">emergency password access</a>
* <a href="#_about_this_document">about this document</a>
* <a href="#_create_userids_on_server_and_client_optional_">create userids on server and client (optional)</a>
* <a href="#_get_pubkey_access_from_client_to_server">get pubkey access from client to server</a>
* <a href="#_get_gitolite_source">get gitolite source</a>
* <a href="#_install_gitolite">install gitolite</a>
* <a href="#_VERY_IMPORTANT_">VERY IMPORTANT...</a>
* <a href="#_examine_what_you_have">examine what you have</a>
* <a href="#_emergency_password_access">emergency password access</a>
----
<a name="about_this_document"></a>
<a name="_about_this_document"></a>
### about this document
@ -40,7 +40,7 @@ you have to run it on your workstation, NOT on the server!**
----
<a name="create_userids_on_server_and_client_optional_"></a>
<a name="_create_userids_on_server_and_client_optional_"></a>
### create userids on server and client (optional)
@ -87,7 +87,7 @@ because I'm not showing the actual "vi" session):
----
<a name="get_pubkey_access_from_client_to_server"></a>
<a name="_get_pubkey_access_from_client_to_server"></a>
### get pubkey access from client to server
@ -136,9 +136,11 @@ Double check to make sure you can log on to `git@server` without a password:
sita@sita-lt:~ $ ssh git@server pwd
/home/git
**DO NOT PROCEED UNTIL THIS WORKS OK!**
----
<a name="get_gitolite_source"></a>
<a name="_get_gitolite_source"></a>
### get gitolite source
@ -150,7 +152,7 @@ Double check to make sure you can log on to `git@server` without a password:
Receiving objects: 100% (1157/1157), 270.08 KiB | 61 KiB/s, done.
Resolving deltas: 100% (756/756), done.
<a name="install_gitolite"></a>
<a name="_install_gitolite"></a>
### install gitolite
@ -221,7 +223,7 @@ install mode that allows you to change the defaults etc.
----
<a name="VERY_IMPORTANT_"></a>
<a name="_VERY_IMPORTANT_"></a>
### VERY IMPORTANT...
@ -235,7 +237,7 @@ non-standard ports were used).
Try out that `tail -31 ./gl-easy-install` too :)
<a name="examine_what_you_have"></a>
<a name="_examine_what_you_have"></a>
### examine what you have
@ -258,7 +260,7 @@ gitolite-admin repo in `~/gitolite-admin`.
And that's really all. Add keys to keydir here, edit conf/gitolite.conf as
needed, then add, commit, and push the changes to the server.
<a name="emergency_password_access"></a>
<a name="_emergency_password_access"></a>
### emergency password access

4
doc/1-migrate.mkd → doc/migrate.mkd
View file

@ -36,8 +36,6 @@ Here's how we migrated my work repos:
Now, log off the server and get back to the client:
[inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
1. follow instructions to install gitolite; see the [install document][inst].
Make sure that you **don't** change the default path for `$REPO_BASE` if
you edit the config file!
@ -87,4 +85,4 @@ Now, log off the server and get back to the client:
5. Check all your changes to your gitolite-admin clone, commit, and push
[mk]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#multikeys
[inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd

62
doc/mirroring.mkd
View file

@ -9,7 +9,7 @@ update, you just add a post-receive hook that says
But life is never that simple...
**This document has been tested using a 3-server setup, all installed using
the "non-root" method (see doc/0-INSTALL.mkd). However, the process is
the "non-root" method (see doc/1-INSTALL.mkd). However, the process is
probably not going to be very forgiving of human error -- like anything that
is this deep in "system admin" territory, errors are likely to be costly. If
you're the kind who hits enter first and then thinks about what he typed,
@ -22,23 +22,23 @@ never *really* lost until you do a `git gc`**.
In this document:
* <a href="#RULE_NUMBER_ONE_">RULE NUMBER ONE!</a>
* <a href="#things_that_will_NOT_be_mirrored_by_this_process">things that will NOT be mirrored by this process</a>
* <a href="#conventions_in_this_document">conventions in this document</a>
* <a href="#setting_up_mirroring">setting up mirroring</a>
* <a href="#install_gitolite_on_all_servers">install gitolite on all servers</a>
* <a href="#generate_keypairs">generate keypairs</a>
* <a href="#setup_the_mirror_shell_on_each_server">setup the mirror-shell on each server</a>
* <a href="#set_slaves_to_slave_mode">set slaves to slave mode</a>
* <a href="#set_slave_server_lists">set slave server lists</a>
* <a href="#syncing_the_mirrors_the_first_time">syncing the mirrors the first time</a>
* <a href="#switching_over">switching over</a>
* <a href="#the_return_of_foo">the return of foo</a>
* <a href="#switching_back">switching back</a>
* <a href="#making_foo_a_slave">making foo a slave</a>
* <a href="#URLs_that_your_users_will_use">URLs that your users will use</a>
* <a href="#_RULE_NUMBER_ONE_">RULE NUMBER ONE!</a>
* <a href="#_things_that_will_NOT_be_mirrored_by_this_process">things that will NOT be mirrored by this process</a>
* <a href="#_conventions_in_this_document">conventions in this document</a>
* <a href="#_setting_up_mirroring">setting up mirroring</a>
* <a href="#_install_gitolite_on_all_servers">install gitolite on all servers</a>
* <a href="#_generate_keypairs">generate keypairs</a>
* <a href="#_setup_the_mirror_shell_on_each_server">setup the mirror-shell on each server</a>
* <a href="#_set_slaves_to_slave_mode">set slaves to slave mode</a>
* <a href="#_set_slave_server_lists">set slave server lists</a>
* <a href="#_syncing_the_mirrors_the_first_time">syncing the mirrors the first time</a>
* <a href="#_switching_over">switching over</a>
* <a href="#_the_return_of_foo">the return of foo</a>
* <a href="#_switching_back">switching back</a>
* <a href="#_making_foo_a_slave">making foo a slave</a>
* <a href="#_URLs_that_your_users_will_use">URLs that your users will use</a>
<a name="RULE_NUMBER_ONE_"></a>
<a name="_RULE_NUMBER_ONE_"></a>
### RULE NUMBER ONE!
@ -52,7 +52,7 @@ Corollary: if the primary went down and you effected a changeover, you must
make sure that the primary does not come up in a push-enabled mode when it
recovers.
<a name="things_that_will_NOT_be_mirrored_by_this_process"></a>
<a name="_things_that_will_NOT_be_mirrored_by_this_process"></a>
### things that will NOT be mirrored by this process
@ -72,7 +72,7 @@ important, (especially the gl-creator, although if your wildcard pattern had
Your best bet is to use rsync for the log files, and tar for the others, at
regular intervals.
<a name="conventions_in_this_document"></a>
<a name="_conventions_in_this_document"></a>
### conventions in this document
@ -80,11 +80,11 @@ The userid hosting gitolite is `gitolite` on all machines. The servers are
foo, bar, and baz. At the beginning, foo is the master, the other 2 are
slaves.
<a name="setting_up_mirroring"></a>
<a name="_setting_up_mirroring"></a>
### setting up mirroring
<a name="install_gitolite_on_all_servers"></a>
<a name="_install_gitolite_on_all_servers"></a>
#### install gitolite on all servers
@ -99,7 +99,7 @@ slaves.
* Use the same "admin key" on all the machines, so that the same person has
gitolite-admin access to all of them.
<a name="generate_keypairs"></a>
<a name="_generate_keypairs"></a>
#### generate keypairs
@ -108,7 +108,7 @@ servers, so first generate keypairs for all of them (`ssh-keygen`) and copy
the `.pub` files to all other servers, named appropriately. So foo will have
bar.pub and baz.pub, etc.
<a name="setup_the_mirror_shell_on_each_server"></a>
<a name="_setup_the_mirror_shell_on_each_server"></a>
#### setup the mirror-shell on each server
@ -136,7 +136,7 @@ Now test this access:
Similarly test the other combinations.
<a name="set_slaves_to_slave_mode"></a>
<a name="_set_slaves_to_slave_mode"></a>
#### set slaves to slave mode
@ -145,7 +145,7 @@ Set slave mode on all the *slave* servers by setting `$GL_SLAVE_MODE = 1`
Leave the master server's file as is.
<a name="set_slave_server_lists"></a>
<a name="_set_slave_server_lists"></a>
#### set slave server lists
@ -181,7 +181,7 @@ port number:
And that's really all there is, unless...
<a name="syncing_the_mirrors_the_first_time"></a>
<a name="_syncing_the_mirrors_the_first_time"></a>
### syncing the mirrors the first time
@ -193,7 +193,7 @@ them up once.
gl-mirror-sync gitolite@bar
# path to "sync" program is ~/.gitolite/src if "from-client" install
<a name="switching_over"></a>
<a name="_switching_over"></a>
### switching over
@ -225,11 +225,11 @@ to have "baz" be a slave.
system comes up. Better still, use extraneous means to block incoming
connections from normal users (out of scope for this document).
<a name="the_return_of_foo"></a>
<a name="_the_return_of_foo"></a>
### the return of foo
<a name="switching_back"></a>
<a name="_switching_back"></a>
#### switching back
@ -260,7 +260,7 @@ Switching back is fairly easy.
* on foo, set slave mode off
* tell everyone to switch back
<a name="making_foo_a_slave"></a>
<a name="_making_foo_a_slave"></a>
#### making foo a slave
@ -281,7 +281,7 @@ this, but YMMV.
----
<a name="URLs_that_your_users_will_use"></a>
<a name="_URLs_that_your_users_will_use"></a>
### URLs that your users will use

0
doc/9-packaging.mkd → doc/packaging.mkd
View file

18
doc/progit-article.mkd
View file

@ -4,6 +4,8 @@ Git has started to become very popular in corporate environments, which tend to
Gitolite allows you to specify permissions not just by repository, but also by branch or tag names within each repository. That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others.
<a name="_Installing_"></a>
### Installing ###
Installing Gitolite is very easy, even if you don't read the extensive documentation that comes with it. You need an account on a Unix server of some kind; various Linux flavours, and Solaris 10, have been tested. You do not need root access, assuming git, perl, and an openssh compatible ssh server are already installed. In the examples below, we will use the `gitolite` account on a host called `gitserver`.
@ -35,10 +37,14 @@ And you're done! Gitolite has now been installed on the server, and you now hav
That last command does produce a fair amount of output, which might be interesting to read. Also, the first time you run this, a new keypair is created; you will have to choose a passphrase or hit enter for none. Why a second keypair is needed, and how it is used, is explained in the "ssh troubleshooting" document that comes with Gitolite. (Hey the documentation has to be good for *something*!)
<a name="_Customising_the_Install_"></a>
### Customising the Install ###
While the default, quick, install works for most people, there are some ways to customise the install if you need to. If you omit the `-q` argument, you get a "verbose" mode install -- detailed information on what the install is doing at each step. The verbose mode also allows you to change certain server-side parameters, such as the location of the actual repositories, by editing an "rc" file that the server uses. This "rc" file is liberally commented so you should be able to make any changes you need quite easily, save it, and continue. This file also contains various settings that you can change to enable or disable some of gitolite's advanced features.
<a name="_Config_File_and_Access_Control_Rules_"></a>
### Config File and Access Control Rules ###
Once the install is done, you switch to the `gitolite-admin` repository (placed in your HOME directory) and poke around to see what you got:
@ -98,6 +104,8 @@ There are two levels of access control in gitolite. The first is at the reposit
The second level, applicable only to "write" access, is by branch or tag within a repository. The username, the access being attempted (`W` or `+`), and the refname being updated are known. The access rules are checked in order of appearance in the config file, looking for a match for this combination (but remember that the refname is regex-matched, not merely string-matched). If a match is found, the push succeeds. A fallthrough results in access being denied.
<a name="_Advanced_Access_Control_with_deny_rules_"></a>
### Advanced Access Control with "deny" rules ###
So far, we've only seen permissions to be one or `R`, `RW`, or `RW+`. However, gitolite allows another permission: `-`, standing for "deny". This gives you a lot more power, at the expense of some complexity, because now fallthrough is not the *only* way for access to be denied, so the *order of the rules now matters*!
@ -110,6 +118,8 @@ Let us say, in the situation above, we want engineers to be able to rewind any b
Again, you simply follow the rules top down until you hit a match for your access mode, or a deny. Non-rewind push to master or integ is allowed by the first rule. A rewind push to those refs does not match the first rule, drops down to the second, and is therefore denied. Any push (rewind or non-rewind) to refs other than master or integ won't match the first two rules anyway, and the third rule allows it.
<a name="_Restricting_pushes_by_files_changed_"></a>
### Restricting pushes by files changed ###
In addition to restricting what branches a user can push changes to, you can also restrict what files they are allowed to touch. For example, perhaps the Makefile (or some other program) is really not supposed to be changed by just anyone, because a lot of things depend on it or would break if the changes are not done *just right*. You can tell gitolite:
@ -123,6 +133,8 @@ In addition to restricting what branches a user can push changes to, you can als
This powerful feature is documented in `conf/example.conf`.
<a name="_Personal_Branches_"></a>
### Personal Branches ###
Gitolite also has a feature called "personal branches" (or rather, "personal branch namespace") that can be very useful in a corporate environment.
@ -133,9 +145,13 @@ This would normally cause the same branch name clutter as in a centralised VCS,
Gitolite lets you define a "personal" or "scratch" namespace prefix for each developer (for example, `refs/personal/<devname>/*`); see the "personal branches" section in `doc/3-faq-tips-etc.mkd` for details.
<a name="_Wildcard_repositories_"></a>
### "Wildcard" repositories ###
Gitolite allows you to specify repositories with wildcards (actually perl regexes), like, for example `assignments/s[0-9][0-9]/a[0-9][0-9]`, to pick a random example. This is a *very* powerful feature, which has to be enabled by setting `$GL_WILDREPOS = 1;` in the rc file. It allows you to assign a new permission mode ("C") which allows users to create repositories based on such wild cards, automatically assigns ownership to the specific user who created it, allows him/her to hand out R and RW permissions to other users to collaborate, etc. This feature is documented in `doc/4-wildcard-repositories.mkd`.
Gitolite allows you to specify repositories with wildcards (actually perl regexes), like, for example `assignments/s[0-9][0-9]/a[0-9][0-9]`, to pick a random example. This is a *very* powerful feature, which has to be enabled by setting `$GL_WILDREPOS = 1;` in the rc file. It allows you to assign a new permission mode ("C") which allows users to create repositories based on such wild cards, automatically assigns ownership to the specific user who created it, allows him/her to hand out R and RW permissions to other users to collaborate, etc. This feature is documented in `doc/wildcard-repositories.mkd`.
<a name="_Other_Features_"></a>
### Other Features ###

18
doc/report-output.mkd
View file

@ -10,14 +10,14 @@ through this document).
In this document:
* <a href="#the_info_command">the "info" command</a>
* <a href="#interpreting_the_output">interpreting the output</a>
* <a href="#using_patterns_to_limit_output">using patterns to limit output</a>
* <a href="#the_expand_command">the "expand" command</a>
* <a href="#_the_info_command">the "info" command</a>
* <a href="#_interpreting_the_output">interpreting the output</a>
* <a href="#_using_patterns_to_limit_output">using patterns to limit output</a>
* <a href="#_the_expand_command">the "expand" command</a>
----
<a name="the_info_command"></a>
<a name="_the_info_command"></a>
### the "info" command
@ -52,7 +52,7 @@ is often blank.
@R_ @W_ testing
R W vkc
<a name="interpreting_the_output"></a>
<a name="_interpreting_the_output"></a>
#### interpreting the output
@ -77,7 +77,7 @@ suffixed by a symbol:
The `_` suffix is special. This says the user has only implicit access (due
to one of the `@all` uses), but no explicit access.
<a name="using_patterns_to_limit_output"></a>
<a name="_using_patterns_to_limit_output"></a>
#### using patterns to limit output
@ -103,7 +103,7 @@ The pattern is also mandatory when an admin wants to find out what access some
*other* user has, which you may have guessed from the syntax in the "usage"
line above.
<a name="the_expand_command"></a>
<a name="_the_expand_command"></a>
### the "expand" command
@ -119,6 +119,6 @@ For each repo found, it searches for it in the config -- either the actual
repo entry (when the repo is not a wildcard repo), or an entry for the
wildcard that matches it -- and reports permissions. It also takes into
account extra permissions enabled by the `setperms` command (see
doc/4-wildcard-repositories.mkd). It shows you the "creator" of the repo as
doc/wildcard-repositories.mkd). It shows you the "creator" of the repo as
an additional column, defaulting to `<gitolite>` if it was not a wildcard
repo.

80
doc/6-ssh-troubleshooting.mkd → doc/ssh-troubleshooting.mkd
View file

@ -2,20 +2,20 @@
In this document:
* <a href="#common_ssh_asks_for_a_password">(common) ssh asks for a password</a>
* <a href="#problems_when_using_package_root_or_non_root_install_methods">problems when using package, root, or non-root install methods</a>
* <a href="#problems_when_using_the_from_client_install_method">problems when using the "from-client" install method</a>
* <a href="#sidebar_why_two_keys_on_client_for_the_admin">(sidebar) why two keys on client for the admin</a>
* <a href="#bypassing_gitolite_without_intending_to">bypassing gitolite without intending to</a>
* <a href="#basic_ssh_troubleshooting_for_the_admin">basic ssh troubleshooting for the admin</a>
* <a href="#windows_issues">windows issues</a>
* <a href="#details">details</a>
* <a href="#files_on_the_server">files on the server</a>
* <a href="#files_on_client">files on client</a>
* <a href="#some_other_tips_and_tricks">some other tips and tricks</a>
* <a href="#giving_shell_access_to_gitolite_users">giving shell access to gitolite users</a>
* <a href="#losing_your_admin_key">losing your admin key</a>
* <a href="#simulating_ssh_copy_id">simulating ssh-copy-id</a>
* <a href="#_common_ssh_asks_for_a_password">(common) ssh asks for a password</a>
* <a href="#_problems_when_using_package_root_or_non_root_install_methods">problems when using package, root, or non-root install methods</a>
* <a href="#_problems_when_using_the_from_client_install_method">problems when using the "from-client" install method</a>
* <a href="#_sidebar_why_two_keys_on_client_for_the_admin">(sidebar) why two keys on client for the admin</a>
* <a href="#_bypassing_gitolite_without_intending_to">bypassing gitolite without intending to</a>
* <a href="#_basic_ssh_troubleshooting_for_the_admin">basic ssh troubleshooting for the admin</a>
* <a href="#_windows_issues">windows issues</a>
* <a href="#_details">details</a>
* <a href="#_files_on_the_server">files on the server</a>
* <a href="#_files_on_client">files on client</a>
* <a href="#_some_other_tips_and_tricks">some other tips and tricks</a>
* <a href="#_giving_shell_access_to_gitolite_users">giving shell access to gitolite users</a>
* <a href="#_losing_your_admin_key">losing your admin key</a>
* <a href="#_simulating_ssh_copy_id">simulating ssh-copy-id</a>
----
@ -36,11 +36,10 @@ code, and documentation.**
Other resources:
* people who think this is too hard should take a look at
[doc/7-install-transcript.mkd][doc7] to **see how simple it *actually*
is**.
* people who think this is too hard should take a look at this
[transcript][] to **see how simple it *actually* is**.
* I **strongly** recommend reading [doc/9-gitolite-and-ssh.mkd][doc9gas],
* I **strongly** recommend reading [doc/gitolite-and-ssh.mkd][doc9gas],
which is a very detailed look at how gitolite uses ssh's features on the
server side. Most people don't know ssh as well as they *think* they do;
even if you don't have any problems right now, it's worth skimming over.
@ -51,7 +50,7 @@ Other resources:
----
<a name="common_ssh_asks_for_a_password"></a>
<a name="_common_ssh_asks_for_a_password"></a>
### (common) ssh asks for a password
@ -136,7 +135,7 @@ This is a quick checklist:
----
<a name="problems_when_using_package_root_or_non_root_install_methods"></a>
<a name="_problems_when_using_package_root_or_non_root_install_methods"></a>
### problems when using package, root, or non-root install methods
@ -163,7 +162,7 @@ first match, the second occurrence (which invokes gitolite) is ignored.
You'll have to (create and) use a different keypair for gitolite access.
<a name="problems_when_using_the_from_client_install_method"></a>
<a name="_problems_when_using_the_from_client_install_method"></a>
### problems when using the "from-client" install method
@ -191,7 +190,9 @@ key.
All this applies *only* to the admin. Normal users will only have one key and
do not need any of this.
<a name="sidebar_why_two_keys_on_client_for_the_admin"></a>
<a name="twokeys"></a>
<a name="_sidebar_why_two_keys_on_client_for_the_admin"></a>
#### (sidebar) why two keys on client for the admin
@ -214,7 +215,7 @@ do not need any of this.
> methods to install gitolite. Please see the [install doc][install] for
> details.
<a name="bypassing_gitolite_without_intending_to"></a>
<a name="_bypassing_gitolite_without_intending_to"></a>
#### bypassing gitolite without intending to
@ -261,7 +262,7 @@ the repo and clones ok. But when you push, gitolite's **update hook** kicks
in, and fails to run because some of the environment variables it is
expecting are not present.
<a name="basic_ssh_troubleshooting_for_the_admin"></a>
<a name="_basic_ssh_troubleshooting_for_the_admin"></a>
#### basic ssh troubleshooting for the admin
@ -310,7 +311,7 @@ from scratch:
That's a long sequence but it should work.
<a name="windows_issues"></a>
<a name="_windows_issues"></a>
### windows issues
@ -326,13 +327,13 @@ how to resolve them and get things working, I'd be happy to credit you and
include it, either directly here if it is short enough or just an external
link, or in contrib/ if it's a longer piece of text.
<a name="details"></a>
<a name="_details"></a>
### details
Here's how it all hangs together.
<a name="files_on_the_server"></a>
<a name="_files_on_the_server"></a>
#### files on the server
@ -364,7 +365,7 @@ Here's how it all hangs together.
argument `sitaram`. This is how gitolite is invoked, (and is told the
user logging in is "sitaram").
<a name="files_on_client"></a>
<a name="_files_on_client"></a>
#### files on client
@ -392,11 +393,11 @@ Here's how it all hangs together.
non-default keypair (unlike command line ssh, which can be given the `-i
~/.ssh/sitaram` flag to do so).
<a name="some_other_tips_and_tricks"></a>
<a name="_some_other_tips_and_tricks"></a>
### some other tips and tricks
<a name="giving_shell_access_to_gitolite_users"></a>
<a name="_giving_shell_access_to_gitolite_users"></a>
#### giving shell access to gitolite users
@ -415,7 +416,7 @@ or
The first method is to be used if you used the **user-install** mode, while
the second method is for the **system-install followed by user-setup** mode
(see doc/0-INSTALL.mkd, section on "install methods", for more on this)
(see doc/1-INSTALL.mkd, section on "install methods", for more on this)
**IMPORTANT UPGRADE NOTE**: previous implementations of this feature were
crap. There was no easy/elegant way to ensure that someone who had repo admin
@ -424,7 +425,7 @@ access would not manage to get himself shell access.
Giving someone shell access requires that you should have shell access in the
first place, so the simplest way is to enable it from the server side only.
<a name="losing_your_admin_key"></a>
<a name="_losing_your_admin_key"></a>
#### losing your admin key
@ -433,7 +434,7 @@ gitolite-admin repository with a fresh key, take a look at the
`src/gl-dont-panic` program. You will need shell access to the server of
course. Run it without arguments to get instructions.
<a name="simulating_ssh_copy_id"></a>
<a name="_simulating_ssh_copy_id"></a>
#### simulating ssh-copy-id
@ -458,11 +459,10 @@ typically) also must be `go-w`, but that needs root. And typically
they're already set that way anyway. (Or if they're not, you've got
bigger problems than gitolite install not working!)]
[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-gitolite-and-ssh.mkd
[install]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
[o3]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#installation_and_setup
[fc]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#from_client_method_install_from_the_client_to_the_server
[urls]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#URLs_for_gitolite_managed_repos
[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite-and-ssh.mkd
[install]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd
[o3]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#methods
[fc]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#fc
[urls]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#URLs_for_gitolite_managed_repos
[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
[doc7]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd
[transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd

0
doc/9-uninstall.mkd → doc/uninstall.mkd
View file

50
doc/4-wildcard-repositories.mkd → doc/wildcard-repositories.mkd
View file

@ -19,17 +19,17 @@ workarounds I may not have the time to code it right away.
In this document:
* <a href="#rc_file_setting_required">rc file setting required</a>
* <a href="#wildcard_repos">wildcard repos</a>
* <a href="#wildcard_repos_with_creator_name_in_them">wildcard repos with creator name in them</a>
* <a href="#wildcard_repos_without_creator_name_in_them">wildcard repos without creator name in them</a>
* <a href="#side_note_line_anchored_regexes">side-note: line-anchored regexes</a>
* <a href="#contrast_with_refexes">contrast with refexes</a>
* <a href="#handing_out_rights_to_wildcard_matched_repos">handing out rights to wildcard-matched repos</a>
* <a href="#setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
* <a href="#reporting">reporting</a>
* <a href="#other_issues_and_discussion">other issues and discussion</a>
* <a href="#how_it_actually_works">how it actually works</a>
* <a href="#_rc_file_setting_required">rc file setting required</a>
* <a href="#_wildcard_repos">wildcard repos</a>
* <a href="#_wildcard_repos_with_creator_name_in_them">wildcard repos with creator name in them</a>
* <a href="#_wildcard_repos_without_creator_name_in_them">wildcard repos without creator name in them</a>
* <a href="#_side_note_line_anchored_regexes">side-note: line-anchored regexes</a>
* <a href="#_contrast_with_refexes">contrast with refexes</a>
* <a href="#_handing_out_rights_to_wildcard_matched_repos">handing out rights to wildcard-matched repos</a>
* <a href="#_setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
* <a href="#_reporting">reporting</a>
* <a href="#_other_issues_and_discussion">other issues and discussion</a>
* <a href="#_how_it_actually_works">how it actually works</a>
----
@ -37,7 +37,7 @@ This document is mostly "by example".
----
<a name="rc_file_setting_required"></a>
<a name="_rc_file_setting_required"></a>
### rc file setting required
@ -45,7 +45,7 @@ This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
on the server. Please search for that variable and see comments around it in
`conf/example.gitolite.rc` for more information on this.
<a name="wildcard_repos"></a>
<a name="_wildcard_repos"></a>
### wildcard repos
@ -53,7 +53,7 @@ Which of these alternatives you choose depends on your needs, and the social
aspects of your environment. The first one is a little more rigid, making it
harder to make mistakes, and the second is more flexible and trusting.
<a name="wildcard_repos_with_creator_name_in_them"></a>
<a name="_wildcard_repos_with_creator_name_in_them"></a>
#### wildcard repos with creator name in them
@ -79,7 +79,7 @@ new repo, as user "u4" (a student):
Notice the *two* empty repo inits, and the order in which they occur ;-)
<a name="wildcard_repos_without_creator_name_in_them"></a>
<a name="_wildcard_repos_without_creator_name_in_them"></a>
#### wildcard repos without creator name in them
@ -106,7 +106,7 @@ and have a TA create the repos in advance.
In either case, they could then use the `setperms` feature to specify which
users are "READERS" and which are "WRITERS". See later for details.
<a name="side_note_line_anchored_regexes"></a>
<a name="_side_note_line_anchored_regexes"></a>
### side-note: line-anchored regexes
@ -123,7 +123,7 @@ But you may be surprised to find that it does not match even
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
metacharacters.
<a name="contrast_with_refexes"></a>
<a name="_contrast_with_refexes"></a>
#### contrast with refexes
@ -135,7 +135,7 @@ if no one will actually push such a branch! You can anchor both sides if you
really care, by using `master$` instead of `master`, but that is *not* the
default for refexes.
<a name="handing_out_rights_to_wildcard_matched_repos"></a>
<a name="_handing_out_rights_to_wildcard_matched_repos"></a>
### handing out rights to wildcard-matched repos
@ -182,23 +182,21 @@ The following points are important:
* whoever you specify as "R" will match the special user READERS. "RW" will
match WRITERS.
<a name="setting_a_gitweb_description_for_a_wildcard_matched_repo"></a>
<a name="_setting_a_gitweb_description_for_a_wildcard_matched_repo"></a>
### setting a gitweb description for a wildcard-matched repo
Similar to the getperms/setperms commands, there are the getdesc/setdesc
commands, thanks to Teemu.
<a name="reporting"></a>
<a name="_reporting"></a>
### reporting
In order to see what repositories were created from a wildcard, use the
"expand" command, described briefly in [doc/report-output.mkd][repout].
[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
<a name="other_issues_and_discussion"></a>
<a name="_other_issues_and_discussion"></a>
### other issues and discussion
@ -220,7 +218,7 @@ In order to see what repositories were created from a wildcard, use the
of the time, it won't be difficult; the fixed prefix will usually be
different anyway so there won't be overlaps.
<a name="how_it_actually_works"></a>
<a name="_how_it_actually_works"></a>
### how it actually works
@ -295,6 +293,4 @@ I hope that helps.
Enjoy, and please use with care. This is pretty powerful stuff. As they say:
if you break it, you get to keep both pieces :)
[jwzq]: http://regex.info/blog/2006-09-15/247
[av]: http://en.wikipedia.org/wiki/Autovivification
[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd