Gitolite README =============== ## about this README **(Github-users: click the "wiki" link before sending me anything via github.)** **This is a minimal README for gitolite**, so you can quickly get started with: * installing gitolite on a fresh userid on a Unix(-like) machine, using ssh * learning enough to do some basic access control **For anything more, you need to look at the complete documentation, at: **. Please go there for what/why/how, concepts, background, troubleshooting, more details on what is covered here, advanced features not covered here, migration from older gitolite, running gitolite over http (rather than ssh), and many more topics. ## Assumptions * You are familiar with: * OS: at least one Unix-like OS * ssh: ssh, ssh keys, ssh authorized keys file * git: basic use of git, bare and non-bare remotes * You are setting up a fresh, ssh-based, instance of gitolite on a Unix machine of some sort. * One is able to connect via ssh and internet to the server using the dedicated account. ## Installation and setup ### server requirements * any unix system * /bin/sh * git 1.6.6 or later * perl 5.8.8 or later * openssh 5.0 or later * a dedicated user account to host the gitolite instance/related repos (in this document, we assume it is "git", but it can be anything; substitute accordingly) * ideally, this user account has * a POSIX compatible shell like /bin/sh * no login/shell customization like .profile, .kshrc, .bashrc, .zshrc|.zshenv, etc. to avoid side effects on gitolite or introduce security problems. However, if the related shell does not set and export the USER environment variable automatically on login, you should accomplish this by putting e.g. the following or a similar line into the ~account/.profile: `export USER=${LOGNAME}` POSIX compatible shells set LOGNAME, but not necessarily USER, so yes, gitolite should use LOGNAME instead. * is accessable by `su - git` or via ssh, ONLY. ### steps to setup an instance (as user "git") * login on your intended server as admin (i.e. a user with additional privileges using sudo, pfexec or similar utilities). * copy the public ssh key of the intended admin of the new gitolite instance to /tmp/admin.pub (or wherever it can be read by user "git"). NOTE that the basename of this file (with `.pub` and everything after an optional `@` including this character itself stripped off) becomes the name of the "virtual" gitolite admin! So don't name it foo.pub or so ;-) * make sure, that the home directory of your "git" account ist set to the directory, where your gitolite instance data (config, logs, repositories) should be stored. E.g.: `grep '^git:' /etc/passwd` * login as "git" on the server. E.g.: `ssh your_server` and than `sudo su - git` * make sure `~git/.ssh/authorized_keys*` is empty or non-existent. E.g.: `rm -f ~/.ssh/authorized_keys*` * setup gitolite using /tmp/admin.pub as the instance admin's public ssh key: `gitolite setup -pk /tmp/admin.pub` * logout If you get any errors please refer to the online documentation whose URL was given at the top of this file. ## adding users and repos *Do NOT add new repos or users manually on the server.* Gitolite users, repos, and access rules are maintained by making changes to a special repo called "gitolite-admin" and *pushing* those changes to the server. To administer your gitolite installation, start by doing this on your workstation (if you have not already done so): git clone git@server_name:gitolite-admin > ------------------------------------------------------------------------- > **NOTE: if you are asked for a password, something went wrong.**. Go hit > the link for the complete documentation earlier in this file. > ------------------------------------------------------------------------- Now if you "cd gitolite-admin", you will see two subdirectories in it: "conf" and "keydir". To add new users alice, bob, and carol, obtain their public keys and add them to "keydir" as alice.pub, bob.pub, and carol.pub respectively. To add a new repo "foo" and give different levels of access to these users, edit the file "conf/gitolite.conf" and add lines like this: repo foo RW+ = alice RW = bob R = carol Once you have made these changes, do something like this: git add conf git add keydir git commit -m "added foo, gave access to alice, bob, carol" git push When the push completes, gitolite will add the new users to `~/.ssh/authorized_keys` on the server, as well as create a new, empty, repo called "foo". ## help for your users Once a user has sent you their public key and you have added them as specified above and given them access, you have to tell them what URL to access their repos at. This is usually "git clone git@host:reponame"; see man git-clone for other forms. **NOTE**: again, if they are asked for a password, something is wrong. If they need to know what repos they have access to, they just have to run "ssh git@host info". ## access rule examples Gitolite's access rules are very powerful. The simplest use was already shown above. Here is a slightly more detailed example: repo foo RW+ = alice - master = bob - refs/tags/v[0-9] = bob RW = bob RW refs/tags/v[0-9] = carol R = dave Here's what these example rules say: * alice can do anything to any branch or tag -- create, push, delete, rewind/overwrite etc. * bob can create or fast-forward push any branch whose name does not start with "master" and create any tag whose name does not start with "v"+digit. * carol can create tags whose names start with "v"+digit. * dave can clone/fetch. Please see the main documentation linked above for all the gory details, as well as more features and examples. ## groups Gitolite allows you to group users or repos for convenience. Here's an example that creates two groups of users: @staff = alice bob carol @interns = ashok repo secret RW = @staff repo foss RW+ = @staff RW = @interns Group lists accumulate. The following two lines have the same effect as the earlier definition of @staff above: @staff = alice bob @staff = carol You can also use group names in other group names: @all-devs = @staff @interns Finally, @all is a special group name that is often convenient to use if you really mean "all repos" or "all users". ## commands Users can run certain commands remotely, using ssh. Running ssh git@host help prints a list of available commands. The most commonly used command is "info". All commands respond to a single argument of "-h" with suitable information. If you have shell on the server, you have a lot more commands available to you; try running "gitolite help". ## LICENSE # contact and support Please see for mailing list and IRC info. # license The gitolite software is copyright Sitaram Chamarty and is licensed under the GPL v2; please see the file called COPYING in the source distribution. Please see for more. > ------------------------------------------------------------------------- > **NOTE**: GIT is a trademark of Software Freedom Conservancy and my use of > "Gitolite" is under license. > -------------------------------------------------------------------------