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
Gitolite is an access control layer on top of git, which allows access control 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: new, the suggested reading order is this:
* the README (this document) for a quick intro * the README (this document) for a quick intro
* **IMPORTANT:** if you don't know anything about ssh, read [this][doc9gas]
* the [INSTALL][install] document * the [INSTALL][install] document
* if you run into trouble with ssh, read [this][doc6sts]
* the [ADMIN][admin] document * 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 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 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 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. 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: In this document:
* <a href="#what">what</a> * <a href="#_what">what</a>
* <a href="#why">why</a> * <a href="#_why">why</a>
* <a href="#other_features">other features</a> * <a href="#_main_features">main features</a>
* <a href="#security">security</a> * <a href="#_support">support</a>
* <a href="#contact_and_license">contact and license</a> * <a href="#_security">security</a>
* <a href="#_contact_and_license">contact and license</a>
---- ----
<a name="what"></a> <a name="_what"></a>
### what ### what
Gitolite allows a server to host many git repositories and provide access to Gitolite lets you use a single user on a server to host many git repositories
many developers, without having to give them real userids on or shell access and provide access to many developers, without having to give them real
to the server. The essential magic in doing this is ssh's pubkey access and userids on or shell access to the server. The essential magic in doing this
the `authorized_keys` file, and the inspiration was an older program called is ssh's pubkey access and the `authorized_keys` file, and the inspiration was
gitosis. an older program called gitosis.
Gitolite can restrict who can read from (clone/fetch) or write to (push) a 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 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 and perl. It also has several other neat features described below and
elsewhere in the [doc/][docs] directory. elsewhere in the [doc/][docs] directory.
<a name="why"></a> <a name="_why"></a>
### why ### why
@ -74,9 +70,9 @@ allow/disallow users access to repos.
But there are several disadvantages here: But there are several disadvantages here:
* every user needs a userid and password on the server. This is usually a * 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 * 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 * *viewing* (aka auditing) the current set of permissions requires running
multiple commands to list directories and their permissions/ownerships, multiple commands to list directories and their permissions/ownerships,
users and their group memberships, and then correlating all these manually 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 read-write access, not only at the repository level, but at the branch
level within repositories. 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 The most important feature I needed was **per-branch permissions**. This is
pretty much mandatory in a corporate environment, and is almost the single 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) * specify repos using patterns (patterns may include creator's name)
* define powerful operations on the server side, even github-like forking * 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 ### 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 ### contact and license
Gitolite is released under GPL v2. See COPYING for details. Gitolite is released under GPL v2. See COPYING for details.
sitaramc@gmail.com * author: sitaramc@gmail.com, sitaram@atc.tcs.com
mailing list: gitolite@googlegroups.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: In this document:
* <a href="#please_read_this_first">please read this first</a> * <a href="#_please_read_this_first">please read this first</a>
* <a href="#important_notes">important notes</a> * <a href="#_important_notes">important notes</a>
* <a href="#conventions_used">conventions used</a> * <a href="#_conventions_used">conventions used</a>
* <a href="#requirements">requirements</a> * <a href="#_requirements">requirements</a>
* <a href="#client_side">client side</a> * <a href="#_client_workstation">client/workstation</a>
* <a href="#server_side">server side</a> * <a href="#_server">server</a>
* <a href="#installation_and_setup">installation and setup</a> * <a href="#_technical_skills">technical skills</a>
* <a href="#package_method_directly_on_the_server_using_RPM_DEB">(package method) directly on the server, using RPM/DEB</a> * <a href="#_installation_and_setup">installation and setup</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="#_install_methods_and_deciding_which_one_to_use">install methods and deciding which one to use</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="#_package_method_directly_on_the_server_using_RPM_DEB">(package method) directly on the server, using RPM/DEB</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="#_root_method_directly_on_the_server_manually_with_root_access">(root method) directly on the server, manually, with root access</a>
* <a href="#URLs_for_gitolite_managed_repos">URLs for gitolite-managed repos</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="#special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</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="#package_method_and_root_method">package method and root method</a> * <a href="#_URLs_for_gitolite_managed_repos">URLs for gitolite-managed repos</a>
* <a href="#from_client_method">from-client method</a> * <a href="#_special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
* <a href="#upgrading">upgrading</a> * <a href="#_package_method_and_root_method">package method and root method</a>
* <a href="#uninstalling">uninstalling</a> * <a href="#_from_client_method">from-client method</a>
* <a href="#cleaning_out_a_botched_install">cleaning out a botched install</a> * <a href="#_upgrading">upgrading</a>
* <a href="#uninstalling_gitolite_completely">uninstalling gitolite completely</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 ### please read this first
<a name="important_notes"></a> <a name="_important_notes"></a>
#### important notes #### important notes
Please make sure you understand the following points first. Please make sure you understand the following points first.
* gitolite is somewhat unusual as far as "server" software goes -- every * gitolite runs as a single user on a server, and is invoked via ssh. Thus,
userid on the server is a potential "gitolite host". every user on the server is a potential "gitolite host".
* gitolite depends **heavily** on ssh pubkey (passwordless) access. Do not * gitolite depends **heavily** on ssh pubkey (passwordless) access. Do not
assume you know all about ssh -- most people **don't**. If in doubt, use 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. administration of gitolite.
To make matters worse, ssh problems in gitolite don't always look like ssh 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 #### conventions used
We assume the admin user is "sitaram", and his workstation is called "client". Throughout the documentation, we use "sitaram" as the admin user, and his
The hosting user is "git", and the server is called "server". Substitute your workstation is called "client". The hosting user is "git", and the server is
values as needed. 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 #### requirements
<a name="client_side"></a> <a name="_client_workstation"></a>
##### client side ##### client/workstation
* git version 1.6.2 or greater * git version 1.6.2 or greater
* even msysgit on Windows is fine; please don't ask me for help if * even msysgit on Windows is fine; please don't ask me for help if
@ -69,9 +93,9 @@ values as needed.
shell is needed shell is needed
* again, msysgit on Windows is fine * 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". * any Unix system with a posix compatible "sh".
* people using "csh" or derivatives please don't ask me for help -- tell * 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) * perl (but since git requires it anyway, you probably have it)
* openssh or any ssh that can understand the `authorized_keys` file format * 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 ### 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 #### (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` * 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 #### (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` * 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 #### (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` * 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 #### (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 The advantage of this method is that it forces you to solve the ssh pubkey
still the one I use for most of my testing. The **main advantage** of this problem **before** attempting to install. It works best if you have dedicated
method is that it **forces you** to solve the ssh pubkey problem **before** userids, one on the server for installing gitolite, and one the client for
attempting to install. Sadly, it also forces the admin to use a **different** administering it.
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.
This method is verbosely documented in [doc/7-install-transcript.mkd][doc7], Sadly, it also forces the admin to use a different URL to access gitolite
including *outputs* of the commands concerned. 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 ### 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 different URL (`gitolite:reponame`) to gain access to the gitolite
repositories. Check [here][twokeys] for why. 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 ### 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 #### 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 don't need to -- the pubkey will allow them to be gitolite admins on their
domain, and that's quite enough for normal operations. domain, and that's quite enough for normal operations.
<a name="from_client_method"></a> <a name="_from_client_method"></a>
#### from-client method #### 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 ~/admin1; git clone gitolite_server_1:gitolite-admin.git
cd ~/admin2; git clone gitolite_server_2:gitolite-admin.git cd ~/admin2; git clone gitolite_server_2:gitolite-admin.git
<a name="upgrading"></a> <a name="_upgrading"></a>
### upgrading ### upgrading
@ -244,11 +307,11 @@ also.
Also, remember that some new features may require additional settings in your Also, remember that some new features may require additional settings in your
`~/.gitolite.rc` file. `~/.gitolite.rc` file.
<a name="uninstalling"></a> <a name="_uninstalling"></a>
### uninstalling ### uninstalling
<a name="cleaning_out_a_botched_install"></a> <a name="_cleaning_out_a_botched_install"></a>
#### cleaning out a botched install #### cleaning out a botched install
@ -266,18 +329,17 @@ here's how to clean the slate.
* remove `~/.gitolite`, `~/.gitolite.rc` and * remove `~/.gitolite`, `~/.gitolite.rc` and
`~/repositories/gitolite-admin.git` `~/repositories/gitolite-admin.git`
<a name="uninstalling_gitolite_completely"></a> <a name="_uninstalling_gitolite_completely"></a>
#### uninstalling gitolite completely #### uninstalling gitolite completely
There's some duplication between this and the previous section, but There's some duplication between this and the previous section, but
uninstalling gitolite is described in great detail in 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 [doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/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/uninstall.mkd
[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-uninstall.mkd [twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd#twokeys
[doc9ssh]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-ssh-tips.mkd [transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd
[twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd#why_two_keys_on_client

84
doc/2-admin.mkd
View file

@ -1,38 +1,46 @@
# administering and running gitolite # 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 *Note*: some of the paths in this document use variable names. Just refer to
`~/.gitolite.rc` for the correct values for *your* installation. `~/.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. 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 ### 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 automatically be created (empty, but clonable) and users' access will be
updated as needed. updated as needed.
<a name="other_features"></a> <a name="_other_features"></a>
### other features ### 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 #### 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, `conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit,
push. push.
<a name="specifying_gitweb_and_daemon_access"></a> <a name="_specifying_gitweb_and_daemon_access"></a>
#### specifying gitweb and daemon access #### 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. so here goes.
To make a repo or repo group accessible via "git daemon", just give read 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] permission to the special user "daemon".
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
There's a special user called "gitweb" also, which works the same way. There's a special user called "gitweb" also, which works the same way.
However, setting a description for the project also enables gitweb permissions 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 -- this includes removing such settings/files if you remove "read" permissions
for the special usernames or remove the description line. for the special usernames or remove the description line.
<a name="custom_hooks"></a> <a name="_custom_hooks"></a>
#### custom hooks #### 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 the hooks directory, please make sure you do not mess with this file
accidentally, or all your fancy per-branch permissions will stop working.** accidentally, or all your fancy per-branch permissions will stop working.**
<a name="hook_chaining"></a> <a name="_hook_chaining"></a>
#### hook chaining #### 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 merely the defaults. You can change them to anything you want; look in
conf/example.gitolite.rc for details. 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 #### 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_BINDIR` -- where all the binaries live
* `GL_ADMINDIR` -- common directory for many gitolite things * `GL_ADMINDIR` -- common directory for many gitolite things
<a name="custom_git_config"></a> <a name="_custom_git_config"></a>
#### custom git config #### 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`, It does not (currently) support other options like `--add`, the `value_regex`,
etc. 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 [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: In this document:
* <a href="#common_errors_and_mistakes">common errors and mistakes</a> * <a href="#_common_errors_and_mistakes">common errors and mistakes</a>
* <a href="#git_version_dependency">git version dependency</a> * <a href="#_git_version_dependency">git version dependency</a>
* <a href="#other_errors_warnings_notes_">other errors, warnings, notes...</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="#_cloning_an_empty_repo">cloning an empty repo</a>
* <a href="#all_syntax_for_repos">`@all` syntax for repos</a> * <a href="#_all_syntax_for_repos">`@all` syntax for repos</a>
* <a href="#umask_setting">umask setting</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="#_getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
* <a href="#features">features</a> * <a href="#_features">features</a>
* <a href="#syntax_and_normal_usage">syntax and normal usage</a> * <a href="#_syntax_and_normal_usage">syntax and normal usage</a>
* <a href="#simpler_syntax">simpler syntax</a> * <a href="#_simpler_syntax">simpler syntax</a>
* <a href="#one_user_many_keys">one user, many keys</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="#_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="#_two_levels_of_access_rights_checking">two levels of access rights checking</a>
* <a href="#better_logging">better logging</a> * <a href="#_better_logging">better logging</a>
* <a href="#exclude_or_deny_rules">"exclude" (or "deny") rules</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_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="#_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="#_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="#_delegating_parts_of_the_config_file">delegating parts of the config file</a>
* <a href="#convenience_features">convenience features</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="#_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="#_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="#_support_for_git_installed_outside_default_PATH">support for git installed outside default PATH</a>
* <a href="#personal_branches">"personal" branches</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="#_custom_hooks_and_custom_git_config">custom hooks and custom git config</a>
* <a href="#bypassing_gitolite">bypassing gitolite</a> * <a href="#_bypassing_gitolite">bypassing gitolite</a>
* <a href="#INconvenience_features">INconvenience features</a> * <a href="#_INconvenience_features">INconvenience features</a>
* <a href="#deleting_a_repo">deleting a repo</a> * <a href="#_deleting_a_repo">deleting a repo</a>
* <a href="#helping_with_gitweb">helping with gitweb</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_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="#_easier_to_link_gitweb_authorisation_with_gitolite">easier to link gitweb authorisation with gitolite</a>
* <a href="#advanced_features">advanced features</a> * <a href="#_advanced_features">advanced features</a>
* <a href="#repos_named_with_wildcards">repos named with wildcards</a> * <a href="#_repos_named_with_wildcards">repos named with wildcards</a>
* <a href="#admin_defined_commands">admin defined commands</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="#_access_control_for_external_commands">access control for external commands</a>
* <a href="#svnserve">svnserve</a> * <a href="#_svnserve">svnserve</a>
* <a href="#design_choices">design choices</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="#_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 ### common errors and mistakes
@ -65,19 +65,19 @@ In this document:
In other words, you used a key that completely bypassed gitolite and went In other words, you used a key that completely bypassed gitolite and went
straight to the shell to do the clone. 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 ### git version dependency
Gitolite (on the server) now refuses to run if git is not at least 1.6.2. 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... ### other errors, warnings, notes...
<a name="cloning_an_empty_repo"></a> <a name="_cloning_an_empty_repo"></a>
#### cloning an empty repo #### 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 seem to hurt anything. [Update 2009-09-14; this has been fixed in git
1.6.4.3] 1.6.4.3]
<a name="all_syntax_for_repos"></a> <a name="_all_syntax_for_repos"></a>
#### `@all` syntax for repos #### `@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. access, we do not support this.
* don't try giving `@all` users some permission for `@all` repos * don't try giving `@all` users some permission for `@all` repos
<a name="umask_setting"></a> <a name="_umask_setting"></a>
#### umask setting #### umask setting
Gitweb not able to read your repos? You can change the umask for newly 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 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 ### getting a tar file from a clone
@ -125,7 +125,7 @@ plain "git archive", because the Makefile adds a file called
make master.tar make master.tar
# or maybe "make pu.tar" # or maybe "make pu.tar"
<a name="features"></a> <a name="_features"></a>
### features ### 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 like "better config file format", gitolite has evolved to have many useful
features than the original goal of branch-level access control. 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 #### syntax and normal usage
<a name="simpler_syntax"></a> <a name="_simpler_syntax"></a>
##### simpler syntax ##### 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. 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 ##### 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@laptop.pub sitaramc@gmail.com
sitaramc@gmail.com@desktop.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 #### 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 ##### 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 Gitolite also allows "exclude" or "deny" rules. See later in this document
for details. for details.
<a name="better_logging"></a> <a name="_better_logging"></a>
##### better logging ##### 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) 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. 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 ##### "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 before the third one, and it has a `-` as the permission, so the push
fails fails
<a name="separating_delete_and_rewind_rights"></a> <a name="_separating_delete_and_rewind_rights"></a>
##### separating delete and rewind rights ##### 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 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. 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 ##### separating create and push rights
@ -406,7 +406,7 @@ Briefly:
Note: you can combine this with the "delete a branch" permissions described in 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. 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 ##### 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. 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 ##### delegating parts of the config file
You can now split up the config file and delegate the authority to specify You can now split up the config file and delegate the authority to specify
access control for their own pieces. See access control for their own pieces. See [delegation][] for details.
[doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
for details.
<a name="convenience_features"></a> <a name="_convenience_features"></a>
#### convenience features #### 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? ##### 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 Gitolite provides two commands (`info` and `expand`) to help you find this
information; please check [doc/report-output.mkd][repout] for details. 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 ##### including config lines from other files
See the entry under "INCLUDE SOME OTHER FILE" in `conf/example.conf`. 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 ##### 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}"; $ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}";
<a name="personal_branches"></a> <a name="_personal_branches"></a>
##### "personal" branches ##### "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 the slashes). At runtime this will match whoever is the current user. Access
is still determined by the right hand side of course. 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 ##### 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 per-repo "gitconfig" settings. Please see `doc/2-admin.mkd` and
`conf/example.conf` for details. `conf/example.conf` for details.
<a name="bypassing_gitolite"></a> <a name="_bypassing_gitolite"></a>
##### bypassing gitolite ##### bypassing gitolite
@ -538,11 +534,11 @@ to set that variable permanently, preferring this mode instead:
GL_BYPASS_UPDATE_HOOK=1 git push GL_BYPASS_UPDATE_HOOK=1 git push
<a name="INconvenience_features"></a> <a name="_INconvenience_features"></a>
#### INconvenience features #### INconvenience features
<a name="deleting_a_repo"></a> <a name="_deleting_a_repo"></a>
##### deleting a repo ##### 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 specified by name in the config file. (Wildcard repos *can* be deleted by the
user; see [here][rmrepo] for details). 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 If you *do* want to permanently delete a *non*-wildcard repo, here's what you
do: do:
@ -561,7 +555,7 @@ do:
* *then* remove the repo from `~/repositories` on the server (or whatever * *then* remove the repo from `~/repositories` on the server (or whatever
you set `$GL_REPO_BASE` to in the `~/.gitolite.rc`) 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 #### 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 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! 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 ##### 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 repo r2
# ...and so on... # ...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 ##### 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 feature and tie it to gitolite. Configuration example can be found in
`contrib/gitweb/`. `contrib/gitweb/`.
<a name="advanced_features"></a> <a name="_advanced_features"></a>
#### advanced features #### advanced features
<a name="repos_named_with_wildcards"></a> <a name="_repos_named_with_wildcards"></a>
##### repos named with wildcards ##### 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 ##### admin defined commands
This requires the wildcards feature to be enabled, but is then an extremely This requires the wildcards feature to be enabled, but is then an extremely
powerful feature. See `doc/admin-defined-commands.mkd`. 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 ##### access control for external commands
@ -681,7 +677,7 @@ server-side command that contains enough information to make an access control
decision. decision.
Note that this is incompatible with giving people shell access as described in 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 subject to this mechanism (it wouldn't make sense to try and control someone
who has shell access anyway). 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 * svnserve (see next section for a brief description; this has been
contributed by Simon and Vladimir) contributed by Simon and Vladimir)
<a name="svnserve"></a> <a name="_svnserve"></a>
###### svnserve ###### 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 for SVN, SVN connectivity will be retained, and users will be able to use
both SVN and git using the same SSH configuration. both SVN and git using the same SSH configuration.
<a name="design_choices"></a> <a name="_design_choices"></a>
### design choices ### 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 #### 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 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 anyway. If you cannot use the easy install and must install manually, I have
clear instructions on how to set it up. 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: In this document:
* <a href="#background">background</a> * <a href="#_background">background</a>
* <a href="#setting_it_up">setting it up</a> * <a href="#_setting_it_up">setting it up</a>
* <a href="#anatomy_of_a_command">anatomy of a command</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="#_example_uses_and_sample_commands_in_contrib">example uses and sample commands in contrib</a>
* <a href="#fork">fork</a> * <a href="#_fork">fork</a>
* <a href="#rmrepo">rmrepo</a> * <a href="#_rmrepo">rmrepo</a>
* <a href="#enable_disable_push_access_temporarily">enable/disable push access temporarily</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="#_bonus_restricted_admin">(bonus) restricted admin</a>
---- ----
<a name="background"></a> <a name="_background"></a>
### background ### 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 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! 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. And that was that. For a couple of days.
Soon, though, I realised that there could be a pretty big bonus in this for 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 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 wildcard repos. (This also means you must set `$GL_WILDREPOS` to "1" in the
rc file). 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 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 (even if it as simple as `personal/CREATOR/.+`), and a way to specify two
categories of permissions for each such user-created repo. 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" I'm sure if you think of more uses you'll send them to me as "contrib"
entries, right? entries, right?
<a name="setting_it_up"></a> <a name="_setting_it_up"></a>
### setting it up ### 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 executable files with those names in this directory. So don't do that -- you
have been warned!** have been warned!**
<a name="anatomy_of_a_command"></a> <a name="_anatomy_of_a_command"></a>
### anatomy of a command ### 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 If you don't like this, roll your own. If you don't like bash, do the eqvt in
your language of choice. 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 ### example uses and sample commands in contrib
<a name="fork"></a> <a name="_fork"></a>
#### fork #### fork
@ -169,6 +164,8 @@ or some such incantation.
<a name="rmrepo"></a> <a name="rmrepo"></a>
<a name="_rmrepo"></a>
#### rmrepo #### rmrepo
This is one thing that you really could not do before this setup was created. 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 script checks to make sure that the repo being deleted was *created* by
the user invoking it. 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 #### 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 exit 0
<a name="bonus_restricted_admin"></a> <a name="_bonus_restricted_admin"></a>
#### (bonus) restricted admin #### (bonus) restricted admin
@ -239,3 +236,7 @@ script to proceed.
[Note that this particular use does not require `$GL_WILDREPOS` to be enabled, [Note that this particular use does not require `$GL_WILDREPOS` to be enabled,
because it's not using any wildcard repos]. 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: In this document:
* <a href="#when_why_do_we_need_it_">when/why do we need it?</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="#_how_do_we_use_it_">how do we use it?</a>
* <a href="#other_optimisations">other optimisations</a> * <a href="#_other_optimisations">other optimisations</a>
* <a href="#what_are_the_downsides_">what are the downsides?</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="#_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? ### 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. You can imagine what that does when you have 10,000 users and 10,000 repos.
Let's just say it's not pretty :) 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? ### 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 That's a lot smaller, and allows orders of magintude more repos and groups to
be supported. be supported.
<a name="other_optimisations"></a> <a name="_other_optimisations"></a>
### other optimisations ### other optimisations
@ -158,8 +158,8 @@ first one):
`GL_NO_DAEMON_NO_GITWEB` is a very useful optimisation that you *must* enable `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 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 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 description and gitweb/daemon access][gwd]" for details). This will save a
of time when you push the gitolite-admin repo with changes. This variable 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 = also control whether "git config" lines (such as `config hooks.emailprefix =
"[gitolite]"`) will be processed or not. "[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 *everything* after the config compile being skipped. In other words, gitolite
is being used **only** for its access control language. 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? ### 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 (If you didn't understand all that, you're probably not using delegation, so
feel free to ignore it!) 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 ### (extra coolness) usergroups and LDAP/similar tools
@ -238,3 +236,5 @@ specified:
@foo = alice @foo = alice
@bar = 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: In this document:
* <a href="#lots_of_repos_lots_of_users">lots of repos, lots of users</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="#_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="#_delegating_ownership_of_groups_of_repos">delegating ownership of groups of repos</a>
* <a href="#security_philosophy_note">security/philosophy note</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 ### lots of repos, lots of users
Gitolite tries to make it easy to manage access to lots of users and repos, Gitolite tries to make it easy to manage access to lots of users and repos,
exploiting commonalities wherever possible. (The example in [this exploiting commonalities wherever possible. It lets you specify bits and
section][ss] should give you an idea). As you can see, it lets you specify pieces of the access control separately -- i.e., *all* the access specs for a
bits and pieces of the access control separately -- i.e., *all* the access certain repo need not be together; they can be scattered, which makes it
specs for a certain repo need not be together; they can be scattered, which easier to manage the sort of slice and dice needed in that example.
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
But eventually the config file will become too big. If you let only one 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 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 It's easier to show how it all works with an example instead of long
descriptions. 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 ### 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 # any other config as usual, including access control lines for any of the
# above projects or groups # 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 ### 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 ### 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 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 *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 "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: In this document:
* <a href="#ssh_basics">ssh basics</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="#_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_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="#_restricting_branch_level_actions">restricting branch level actions</a>
---- ----
<a name="ssh_basics"></a> <a name="_ssh_basics"></a>
### ssh basics ### 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 **This is the backbone of what makes gitolite work; please make sure you
understand this** 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? ### 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" logging in as the same remote user "git"
* how does it restrict what I can do within a repository * 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 #### 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 But this cannot differentiate between different branches within a repo; that
has to be done separately. has to be done separately.
<a name="restricting_branch_level_actions"></a> <a name="_restricting_branch_level_actions"></a>
#### restricting branch level actions #### 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: In this document:
* <a href="#hooks_used_by_gitolite">hooks used by gitolite</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="#_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_from_client_method">the "from-client" method</a>
* <a href="#the_other_3_methods">the other 3 methods</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_GL_PACKAGE_HOOKS_directory">the `GL_PACKAGE_HOOKS` directory</a>
* <a href="#the_HOME_gitolite_directory">the `$HOME/.gitolite` directory</a> * <a href="#_the_HOME_gitolite_directory">the `$HOME/.gitolite` directory</a>
* <a href="#why_two_places_">why two places?</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="#_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="#_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 ### 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 The final objective of all this is that each repo's `hooks/` directory should
get all the hooks that it is meant to get. 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? ### **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 `hooks/gitolite-admin` directories. This depends on which install method you
used. 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 #### 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 method; skip to the next section ("when do hooks propagate") if you installed
using the "from-client" method. using the "from-client" method.
<a name="the_other_3_methods"></a> <a name="_the_other_3_methods"></a>
#### the other 3 methods #### 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 ##### 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 So now we know there's a location called `$GL_PACKAGE_HOOKS` where you can
place your hooks. place your hooks.
<a name="the_HOME_gitolite_directory"></a> <a name="_the_HOME_gitolite_directory"></a>
##### the `$HOME/.gitolite` directory ##### 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. 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? #### 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 thoroughly test this later; for now, just ignore the extra files you see in
there; they're harmless/redundant (TODO)] 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 #### 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 *strongly* suggest putting them in `$GL_PACKAGE_HOOKS` and ignoring
`$HOME/.gitolite` completely. `$HOME/.gitolite` completely.
<a name="when_do_hooks_propagate_"></a> <a name="_when_do_hooks_propagate_"></a>
### **when** do hooks propagate? ### **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 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. 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: In this document:
* <a href="#about_this_document">about this document</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="#_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_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="#_get_gitolite_source">get gitolite source</a>
* <a href="#install_gitolite">install gitolite</a> * <a href="#_install_gitolite">install gitolite</a>
* <a href="#VERY_IMPORTANT_">VERY IMPORTANT...</a> * <a href="#_VERY_IMPORTANT_">VERY IMPORTANT...</a>
* <a href="#examine_what_you_have">examine what you have</a> * <a href="#_examine_what_you_have">examine what you have</a>
* <a href="#emergency_password_access">emergency password access</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 ### 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) ### 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 ### 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 sita@sita-lt:~ $ ssh git@server pwd
/home/git /home/git
**DO NOT PROCEED UNTIL THIS WORKS OK!**
---- ----
<a name="get_gitolite_source"></a> <a name="_get_gitolite_source"></a>
### get gitolite source ### 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. Receiving objects: 100% (1157/1157), 270.08 KiB | 61 KiB/s, done.
Resolving deltas: 100% (756/756), done. Resolving deltas: 100% (756/756), done.
<a name="install_gitolite"></a> <a name="_install_gitolite"></a>
### install gitolite ### 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... ### VERY IMPORTANT...
@ -235,7 +237,7 @@ non-standard ports were used).
Try out that `tail -31 ./gl-easy-install` too :) 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 ### 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 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. 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 ### 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: 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]. 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 Make sure that you **don't** change the default path for `$REPO_BASE` if
you edit the config file! 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 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 [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... But life is never that simple...
**This document has been tested using a 3-server setup, all installed using **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 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 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, 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: In this document:
* <a href="#RULE_NUMBER_ONE_">RULE NUMBER ONE!</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="#_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="#_conventions_in_this_document">conventions in this document</a>
* <a href="#setting_up_mirroring">setting up mirroring</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="#_install_gitolite_on_all_servers">install gitolite on all servers</a>
* <a href="#generate_keypairs">generate keypairs</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="#_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_slaves_to_slave_mode">set slaves to slave mode</a>
* <a href="#set_slave_server_lists">set slave server lists</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="#_syncing_the_mirrors_the_first_time">syncing the mirrors the first time</a>
* <a href="#switching_over">switching over</a> * <a href="#_switching_over">switching over</a>
* <a href="#the_return_of_foo">the return of foo</a> * <a href="#_the_return_of_foo">the return of foo</a>
* <a href="#switching_back">switching back</a> * <a href="#_switching_back">switching back</a>
* <a href="#making_foo_a_slave">making foo a slave</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="#_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! ### 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 make sure that the primary does not come up in a push-enabled mode when it
recovers. 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 ### 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 Your best bet is to use rsync for the log files, and tar for the others, at
regular intervals. regular intervals.
<a name="conventions_in_this_document"></a> <a name="_conventions_in_this_document"></a>
### conventions in this document ### 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 foo, bar, and baz. At the beginning, foo is the master, the other 2 are
slaves. slaves.
<a name="setting_up_mirroring"></a> <a name="_setting_up_mirroring"></a>
### setting up mirroring ### setting up mirroring
<a name="install_gitolite_on_all_servers"></a> <a name="_install_gitolite_on_all_servers"></a>
#### install gitolite on all servers #### 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 * Use the same "admin key" on all the machines, so that the same person has
gitolite-admin access to all of them. gitolite-admin access to all of them.
<a name="generate_keypairs"></a> <a name="_generate_keypairs"></a>
#### generate keypairs #### 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 the `.pub` files to all other servers, named appropriately. So foo will have
bar.pub and baz.pub, etc. 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 #### setup the mirror-shell on each server
@ -136,7 +136,7 @@ Now test this access:
Similarly test the other combinations. 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 #### 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. 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 #### set slave server lists
@ -181,7 +181,7 @@ port number:
And that's really all there is, unless... 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 ### syncing the mirrors the first time
@ -193,7 +193,7 @@ them up once.
gl-mirror-sync gitolite@bar gl-mirror-sync gitolite@bar
# path to "sync" program is ~/.gitolite/src if "from-client" install # path to "sync" program is ~/.gitolite/src if "from-client" install
<a name="switching_over"></a> <a name="_switching_over"></a>
### switching over ### switching over
@ -225,11 +225,11 @@ to have "baz" be a slave.
system comes up. Better still, use extraneous means to block incoming system comes up. Better still, use extraneous means to block incoming
connections from normal users (out of scope for this document). 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 ### the return of foo
<a name="switching_back"></a> <a name="_switching_back"></a>
#### switching back #### switching back
@ -260,7 +260,7 @@ Switching back is fairly easy.
* on foo, set slave mode off * on foo, set slave mode off
* tell everyone to switch back * tell everyone to switch back
<a name="making_foo_a_slave"></a> <a name="_making_foo_a_slave"></a>
#### making foo a slave #### 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 ### 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. 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 ###
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`. 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*!) 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 ### ### 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. 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 ### ### 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: 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. 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 ### ### 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*! 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. 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 ### ### 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: 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`. This powerful feature is documented in `conf/example.conf`.
<a name="_Personal_Branches_"></a>
### Personal Branches ### ### Personal Branches ###
Gitolite also has a feature called "personal branches" (or rather, "personal branch namespace") that can be very useful in a corporate environment. 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. 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 ### ### "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 ### ### Other Features ###

18
doc/report-output.mkd
View file

@ -10,14 +10,14 @@ through this document).
In this document: In this document:
* <a href="#the_info_command">the "info" command</a> * <a href="#_the_info_command">the "info" command</a>
* <a href="#interpreting_the_output">interpreting the output</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="#_using_patterns_to_limit_output">using patterns to limit output</a>
* <a href="#the_expand_command">the "expand" command</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 ### the "info" command
@ -52,7 +52,7 @@ is often blank.
@R_ @W_ testing @R_ @W_ testing
R W vkc R W vkc
<a name="interpreting_the_output"></a> <a name="_interpreting_the_output"></a>
#### interpreting the output #### interpreting the output
@ -77,7 +77,7 @@ suffixed by a symbol:
The `_` suffix is special. This says the user has only implicit access (due The `_` suffix is special. This says the user has only implicit access (due
to one of the `@all` uses), but no explicit access. 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 #### 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" *other* user has, which you may have guessed from the syntax in the "usage"
line above. line above.
<a name="the_expand_command"></a> <a name="_the_expand_command"></a>
### the "expand" command ### 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 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 wildcard that matches it -- and reports permissions. It also takes into
account extra permissions enabled by the `setperms` command (see 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 an additional column, defaulting to `<gitolite>` if it was not a wildcard
repo. repo.

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

@ -2,20 +2,20 @@
In this document: In this document:
* <a href="#common_ssh_asks_for_a_password">(common) ssh asks for a password</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_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="#_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="#_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="#_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="#_basic_ssh_troubleshooting_for_the_admin">basic ssh troubleshooting for the admin</a>
* <a href="#windows_issues">windows issues</a> * <a href="#_windows_issues">windows issues</a>
* <a href="#details">details</a> * <a href="#_details">details</a>
* <a href="#files_on_the_server">files on the server</a> * <a href="#_files_on_the_server">files on the server</a>
* <a href="#files_on_client">files on client</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="#_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="#_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="#_losing_your_admin_key">losing your admin key</a>
* <a href="#simulating_ssh_copy_id">simulating ssh-copy-id</a> * <a href="#_simulating_ssh_copy_id">simulating ssh-copy-id</a>
---- ----
@ -36,11 +36,10 @@ code, and documentation.**
Other resources: Other resources:
* people who think this is too hard should take a look at * people who think this is too hard should take a look at this
[doc/7-install-transcript.mkd][doc7] to **see how simple it *actually* [transcript][] to **see how simple it *actually* is**.
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 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; 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. 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 ### (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 ### 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. 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 ### 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 All this applies *only* to the admin. Normal users will only have one key and
do not need any of this. 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 #### (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 > methods to install gitolite. Please see the [install doc][install] for
> details. > details.
<a name="bypassing_gitolite_without_intending_to"></a> <a name="_bypassing_gitolite_without_intending_to"></a>
#### bypassing gitolite without intending to #### 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 in, and fails to run because some of the environment variables it is
expecting are not present. 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 #### basic ssh troubleshooting for the admin
@ -310,7 +311,7 @@ from scratch:
That's a long sequence but it should work. That's a long sequence but it should work.
<a name="windows_issues"></a> <a name="_windows_issues"></a>
### windows issues ### 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 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. link, or in contrib/ if it's a longer piece of text.
<a name="details"></a> <a name="_details"></a>
### details ### details
Here's how it all hangs together. 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 #### 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 argument `sitaram`. This is how gitolite is invoked, (and is told the
user logging in is "sitaram"). user logging in is "sitaram").
<a name="files_on_client"></a> <a name="_files_on_client"></a>
#### files on client #### 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 non-default keypair (unlike command line ssh, which can be given the `-i
~/.ssh/sitaram` flag to do so). ~/.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 ### 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 #### 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 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 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 **IMPORTANT UPGRADE NOTE**: previous implementations of this feature were
crap. There was no easy/elegant way to ensure that someone who had repo admin 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 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. 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 #### 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 `src/gl-dont-panic` program. You will need shell access to the server of
course. Run it without arguments to get instructions. 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 #### 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 they're already set that way anyway. (Or if they're not, you've got
bigger problems than gitolite install not working!)] 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/gitolite-and-ssh.mkd
[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-gitolite-and-ssh.mkd [install]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd
[install]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd [o3]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#methods
[o3]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#installation_and_setup [fc]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#fc
[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/1-INSTALL.mkd#URLs_for_gitolite_managed_repos
[urls]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#URLs_for_gitolite_managed_repos
[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd [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: In this document:
* <a href="#rc_file_setting_required">rc file setting required</a> * <a href="#_rc_file_setting_required">rc file setting required</a>
* <a href="#wildcard_repos">wildcard repos</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_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="#_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="#_side_note_line_anchored_regexes">side-note: line-anchored regexes</a>
* <a href="#contrast_with_refexes">contrast with refexes</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="#_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="#_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="#_reporting">reporting</a>
* <a href="#other_issues_and_discussion">other issues and discussion</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="#_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 ### 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 on the server. Please search for that variable and see comments around it in
`conf/example.gitolite.rc` for more information on this. `conf/example.gitolite.rc` for more information on this.
<a name="wildcard_repos"></a> <a name="_wildcard_repos"></a>
### wildcard repos ### 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 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. 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 #### 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 ;-) 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 #### 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 In either case, they could then use the `setperms` feature to specify which
users are "READERS" and which are "WRITERS". See later for details. 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 ### 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 `^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
metacharacters. metacharacters.
<a name="contrast_with_refexes"></a> <a name="_contrast_with_refexes"></a>
#### contrast with refexes #### 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 really care, by using `master$` instead of `master`, but that is *not* the
default for refexes. 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 ### 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 * whoever you specify as "R" will match the special user READERS. "RW" will
match WRITERS. 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 ### setting a gitweb description for a wildcard-matched repo
Similar to the getperms/setperms commands, there are the getdesc/setdesc Similar to the getperms/setperms commands, there are the getdesc/setdesc
commands, thanks to Teemu. commands, thanks to Teemu.
<a name="reporting"></a> <a name="_reporting"></a>
### reporting ### reporting
In order to see what repositories were created from a wildcard, use the In order to see what repositories were created from a wildcard, use the
"expand" command, described briefly in [doc/report-output.mkd][repout]. "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 ### 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 of the time, it won't be difficult; the fixed prefix will usually be
different anyway so there won't be overlaps. 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 ### 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: Enjoy, and please use with care. This is pretty powerful stuff. As they say:
if you break it, you get to keep both pieces :) if you break it, you get to keep both pieces :)
[jwzq]: http://regex.info/blog/2006-09-15/247 [repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
[av]: http://en.wikipedia.org/wiki/Autovivification