quick install in main README

requested by someone who told me it's high time I catered to the experts
too, and saved them some time on the install!

I took the opportunity to streamline the README (especially the "what"
section), and to prioritise the non-root method over the root method in
the install doc.
This commit is contained in:
Sitaram Chamarty 2011-08-25 08:56:19 +05:30
parent 6a3cd5d6b1
commit ddf4330d1e
2 changed files with 114 additions and 98 deletions

View file

@ -5,15 +5,63 @@
Gitolite allows you to setup git hosting on a central server, with Gitolite allows you to setup git hosting on a central server, with
fine-grained access control and many (many!) more powerful features. fine-grained access control and many (many!) more powerful features.
**Impatient?** The [install][install] document has a quick install section at ----
the top. Just remember that "impatient" does not always mean "successful" ;-)
In this document:
* <a href="#_quick_install">quick install</a>
* <a href="#_what">what</a>
* <a href="#_why">why</a>
* <a href="#_main_features">main features</a>
* <a href="#_security">security</a>
* <a href="#_contact_and_license">contact and license</a>
---- ----
Gitolite is an access control layer on top of git, which allows access control <a name="_quick_install"></a>
down to the branch level, including specifying who can and cannot *rewind* a
given branch. [Here][who]'s some information on some of the projects and ### quick install
people using gitolite (and who, in turn, have helped shape its features).
If you're comfortable with Unix and ssh, the following steps should work.
<font color="gray">(However, gitolite has lots and lots of useful features;
don't miss out on them by skipping the excellent
[documentation][docs]!)</font>
* create a user called `git`. Login to this user.
* copy your ssh pubkey from your workstation. Rename it to `YourName.pub`.
* now run these commands:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
gl-setup ~/YourName.pub
You're done. Now run `git clone git@server:gitolite-admin` on your
workstation and [add users and repos][aur].
[aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos
<a name="_what"></a>
### what
Gitolite is an access control layer on top of git. Here's an "executive
summary":
* use a single unix user ("real" user) on the server
* provide access to many gitolite users
* they are not "real" users
* they do not get shell access
* control access to many git repositories
* read access controlled at the repo level
* write access controlled at the branch/tag/file/directory level,
including who can rewind, create, and delete branches/tags
* can be installed without root access, assuming git and perl are already
installed
* authentication is most commonly done using sshd, but you can also use
httpd if you prefer (this may require root access).
* several other neat features described below and elsewhere in the
[doc/][docs] directory.
Gitolite comes with a **huge** amount of documentation. If you're absolutely 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:
@ -27,36 +75,11 @@ new, the suggested reading order is this:
* (if you're migrating from gitosis, read [this][migr]) * (if you're migrating from gitosis, read [this][migr])
There is also a **[master TOC of all gitolite documentation][docs]**; use your There is also a **[master TOC of all gitolite documentation][docs]**; use your
browser's search function (Ctrl-F, usually) to look for likely sounding words browser's search function to look for likely sounding words or just browse
or just browse around -- you never know what you'll find! around -- you never know what you'll find!
---- [Here][who]'s some information on some of the projects and
people using gitolite (and who, in turn, have helped shape its features).
In this document:
* <a href="#_what">what</a>
* <a href="#_why">why</a>
* <a href="#_main_features">main features</a>
* <a href="#_security">security</a>
* <a href="#_contact_and_license">contact and license</a>
----
<a name="_what"></a>
### what
Gitolite lets you use a single user on a server to host many git repositories
and provide access to many developers, without having to give them real
userids on or shell access to the server. Authentication is most commonly
done using sshd, but you can also use httpd if you prefer.
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
very important in a corporate environment. Gitolite can be installed without
requiring root permissions, and with no additional software than git itself
and perl. It also has several other neat features described below and
elsewhere in the [doc/][docs] directory.
<a name="_why"></a> <a name="_why"></a>

View file

@ -6,12 +6,12 @@ http URLs, read [this][http] to install gitolite to support "smart http").
In this document: In this document:
* <a href="#_Impatient_to_install_">Impatient to install?</a> * <a href="#_installing_and_upgrading_gitolite">installing and upgrading gitolite</a>
* <a href="#_side_note_upgrading">(side note) upgrading</a> * <a href="#_side_note_upgrading">(side note) upgrading</a>
* <a href="#_package_method">package method</a> * <a href="#_package_method">package method</a>
* <a href="#_root_method">root method</a>
* <a href="#_non_root_method">non-root method</a> * <a href="#_non_root_method">non-root method</a>
* <a href="#_upgrading_from_from_client_method_to_non_root_method">upgrading from from-client method to non-root method</a> * <a href="#_upgrading_from_from_client_method_to_non_root_method">upgrading from from-client method to non-root method</a>
* <a href="#_root_method">root method</a>
* <a href="#_troubleshooting">troubleshooting</a> * <a href="#_troubleshooting">troubleshooting</a>
* <a href="#_important_points_to_note">important points to note</a> * <a href="#_important_points_to_note">important points to note</a>
* <a href="#_naming_conventions_used">naming conventions used</a> * <a href="#_naming_conventions_used">naming conventions used</a>
@ -30,36 +30,27 @@ In this document:
---- ----
<a name="_Impatient_to_install_"></a> <a name="_installing_and_upgrading_gitolite"></a>
### Impatient to install? ### installing and upgrading gitolite
This top section is for the impatient. You might qualify if you can This section tells you how to install/upgrade gitolite, without too much
understand the following: background. Later sections have more details and troubleshooting info; please
read them before asking for help if you have problems.
> ---- A bare minimum gitolite setup has:
> A bare minimum gitolite setup has: * a server
* a "hosting user" on the server (a real Unix userid; we use "git" in this
document, although RPM/DEB installs use "gitolite")
* a virtual "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
> * a server Gitolite allows 3 methods of install. The two most common are (1) the
> * a "hosting user" on the server (a real Unix userid; we use "git" in **package method**, used if you have a gitolite RPM or a DEB available, and
this document, although RPM/DEB installs use "gitolite") (2) the **non-root method** which is the preferred manual install mode. Less
> * a virtual "admin user" -- the user who sets up gitolite and configures it commonly used is (3) the **root method**, which is useful if you plan to have
> * the admin user's client or workstation, from which he does all his work multiple "hosting users" on the same server.
> ----
If you didn't get all that, or thought you did then ran into problems,
beg/borrow some patience and read the rest of this document before trying it
again.
Gitolite allows 3 methods of install:
* **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
These install methods are described in detail below. (*Once you finish the These install methods are described in detail below. (*Once you finish the
install, read the [admin document][admin] to administer your gitolite install, read the [admin document][admin] to administer your gitolite
@ -83,8 +74,9 @@ filename as an argument.
#### package method #### package method
(Unlike the rest of this document, this specific method uses "gitolite" as the (Unlike in the rest of this document, we use "gitolite" as the "hosting user"
"hosting user" instead of "git", because that is what the RPM/DEB creates). instead of "git" here, because that is the user that both the Fedora and
Debian packages create. Your distro/OS may vary.)
On your *workstation*: On your *workstation*:
@ -105,45 +97,14 @@ On your *workstation*:
git clone gitolite@server:gitolite-admin git clone gitolite@server:gitolite-admin
<a name="_root_method"></a>
#### root method
On your *workstation*:
* copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server
On your *server*, as *root*:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
# defaults to being the same as:
# src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
# to upgrade gitolite, repeat the above commands. Make sure you use the
# same arguments for the last command each time.
# now create your "hosting user" ('git' in our examples) using whatever
# command your distro expects you to use
# switch to the hosting user
su - git
# (now as git)
gl-setup /tmp/YourName.pub
On your *workstation*:
git clone git@server:gitolite-admin
<a name="_non_root_method"></a> <a name="_non_root_method"></a>
#### non-root method #### non-root method
**IMPORTANT WARNING -- IGNORE AT YOUR PERIL**: if you want to use this method **IMPORTANT WARNING -- IGNORE AT YOUR PERIL**: if you want to use this method
you had better know the password to the hosting user on the server, just in you had better know the password to the hosting user on the server, or be able
case you manage to lock yourself out by messing with the keys. to `su` to it from root, just in case you manage to lock yourself out by
messing with the keys.
**NOTE**: This method is exhaustively described in the [tutorial][tut], if **NOTE**: This method is exhaustively described in the [tutorial][tut], if
you're interested. (That tutorial is by someone else but it's nice enough for you're interested. (That tutorial is by someone else but it's nice enough for
@ -204,6 +165,38 @@ There are many, many ways to skin this cat; here's one way:
Now save the file. Now save the file.
<a name="_root_method"></a>
#### root method
On your *workstation*:
* copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server
On your *server*, as *root*:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
# defaults to being the same as:
# src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
# to upgrade gitolite, repeat the above commands. Make sure you use the
# same arguments for the last command each time.
# now create your "hosting user" ('git' in our examples) using whatever
# command your distro expects you to use
# switch to the hosting user
su - git
# (now as git)
gl-setup /tmp/YourName.pub
On your *workstation*:
git clone git@server:gitolite-admin
---- ----
<a name="_troubleshooting"></a> <a name="_troubleshooting"></a>