diff --git a/README.mkd b/README.mkd index 269ca87..70ecac6 100644 --- a/README.mkd +++ b/README.mkd @@ -5,15 +5,63 @@ Gitolite allows you to setup git hosting on a central server, with 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: + + * quick install + * what + * why + * main features + * security + * contact and license ---- -Gitolite is an access control layer on top of git, which allows access control -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 -people using gitolite (and who, in turn, have helped shape its features). + + +### quick install + +If you're comfortable with Unix and ssh, the following steps should work. +(However, gitolite has lots and lots of useful features; +don't miss out on them by skipping the excellent +[documentation][docs]!) + + * 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 + + + +### 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 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]) 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 -or just browse around -- you never know what you'll find! +browser's search function to look for likely sounding words or just browse +around -- you never know what you'll find! ----- - -In this document: - - * what - * why - * main features - * security - * contact and license - ----- - - - -### 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. +[Here][who]'s some information on some of the projects and +people using gitolite (and who, in turn, have helped shape its features). diff --git a/doc/1-INSTALL.mkd b/doc/1-INSTALL.mkd index 2b724ca..b73fa32 100644 --- a/doc/1-INSTALL.mkd +++ b/doc/1-INSTALL.mkd @@ -6,12 +6,12 @@ http URLs, read [this][http] to install gitolite to support "smart http"). In this document: - * Impatient to install? + * installing and upgrading gitolite * (side note) upgrading * package method - * root method * non-root method * upgrading from from-client method to non-root method + * root method * troubleshooting * important points to note * naming conventions used @@ -30,36 +30,27 @@ In this document: ---- - + -### Impatient to install? +### installing and upgrading gitolite -This top section is for the impatient. You might qualify if you can -understand the following: +This section tells you how to install/upgrade gitolite, without too much +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 -> * 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 - -> ---- - -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 +Gitolite allows 3 methods of install. The two most common are (1) the +**package method**, used if you have a gitolite RPM or a DEB available, and +(2) the **non-root method** which is the preferred manual install mode. Less +commonly used is (3) the **root method**, which is useful if you plan to have +multiple "hosting users" on the same server. These install methods are described in detail below. (*Once you finish the install, read the [admin document][admin] to administer your gitolite @@ -83,8 +74,9 @@ filename as an argument. #### package method -(Unlike the rest of this document, this specific method uses "gitolite" as the -"hosting user" instead of "git", because that is what the RPM/DEB creates). +(Unlike in the rest of this document, we use "gitolite" as the "hosting user" +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*: @@ -105,45 +97,14 @@ On your *workstation*: git clone gitolite@server:gitolite-admin - - -#### 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 - #### non-root 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 -case you manage to lock yourself out by messing with the keys. +you had better know the password to the hosting user on the server, or be able +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 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. + + +#### 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 + ----