README.markdown

   1 Gitolite README
   2 ===============
   3
   4 ## about this README
   5
   6 **(Github-users: click the "wiki" link before sending me anything via github.)**
   7
   8 **This is a minimal README for gitolite**, so you can quickly get started with:
   9
  10 *   installing gitolite on a fresh userid on a Unix(-like) machine, using ssh
  11 *   learning enough to do some basic access control
  12
  13 **For anything more, you need to look at the complete documentation, at:
  14 <http://gitolite.com/gitolite>**.  Please go there for what/why/how, concepts,
  15 background, troubleshooting, more details on what is covered here, advanced
  16 features not covered here, migration from older gitolite, running gitolite
  17 over http (rather than ssh), and many more topics.
  18
  19 <!-- --------------------------------------------------------------------- -->
  20
  21 ## Assumptions
  22
  23 *   You are familiar with:
  24     *   OS: at least one Unix-like OS
  25     *   ssh: ssh, ssh keys, ssh authorized keys file
  26     *   git: basic use of git, bare and non-bare remotes
  27
  28 *   You are setting up a fresh, ssh-based, installation of gitolite on a Unix
  29     machine of some sort.
  30
  31 *   You have root access, or someone has created a userid called "git" for you
  32     to use and given you a password for it.  This is a brand new userid (or
  33     you have deleted everything but `.bashrc` and similar files to make it
  34     look like one!)
  35
  36 *   If your server is not connected to the internet, you know how to clone the
  37     gitolite source code by using some in-between server or "git bundle".
  38
  39 <!-- --------------------------------------------------------------------- -->
  40
  41 ## Installation and setup
  42
  43 ### server requirements
  44
  45 *   any unix system
  46 *   sh
  47 *   git 1.6.6 or later
  48 *   perl 5.8.8 or later
  49 *   openssh 5.0 or later
  50 *   a dedicated userid to host the repos (in this document, we assume it is
  51     "git", but it can be anything; substitute accordingly)
  52 *   this user id does NOT currently have any ssh pubkey-based access
  53     *   ideally, this user id has shell access ONLY by "su - git" from some
  54         other userid on the same server (this ensure minimal confusion for ssh
  55         newbies!)
  56
  57 ### steps to install
  58
  59 First, prepare the ssh key:
  60
  61 *   login to "git" on the server
  62 *   make sure `~/.ssh/authorized_keys` is empty or non-existent
  63 *   make sure your ssh public key from your workstation has been copied as
  64     $HOME/YourName.pub
  65
  66 Next, install gitolite by running these commands:
  67
  68     git clone git://github.com/sitaramc/gitolite
  69     mkdir -p $HOME/bin
  70     gitolite/install -to $HOME/bin
  71
  72 Finally, setup gitolite with yourself as the administrator:
  73
  74     gitolite setup -pk YourName.pub
  75
  76 If the last command doesn't run perhaps "bin" is not in your "PATH". You can
  77 either add it, or just run:
  78
  79     $HOME/bin/gitolite setup -pk YourName.pub
  80
  81 If you get any other errors please refer to the online documentation whose URL
  82 was given at the top of this file.
  83
  84 ## adding users and repos
  85
  86 *Do NOT add new repos or users manually on the server.*  Gitolite users,
  87 repos, and access rules are maintained by making changes to a special repo
  88 called "gitolite-admin" and *pushing* those changes to the server.
  89
  90 To administer your gitolite installation, start by doing this on your
  91 workstation (if you have not already done so):
  92
  93     git clone git@host:gitolite-admin
  94
  95 >   -------------------------------------------------------------------------
  96
  97 >   **NOTE: if you are asked for a password, something went wrong.**.  Go hit
  98 >   the link for the complete documentation earlier in this file.
  99
 100 >   -------------------------------------------------------------------------
 101
 102 Now if you "cd gitolite-admin", you will see two subdirectories in it: "conf"
 103 and "keydir".
 104
 105 To add new users alice, bob, and carol, obtain their public keys and add them
 106 to "keydir" as alice.pub, bob.pub, and carol.pub respectively.
 107
 108 To add a new repo "foo" and give different levels of access to these
 109 users, edit the file "conf/gitolite.conf" and add lines like this:
 110
 111     repo foo
 112         RW+         =   alice
 113         RW          =   bob
 114         R           =   carol
 115
 116 Once you have made these changes, do something like this:
 117
 118     git add conf
 119     git add keydir
 120     git commit -m "added foo, gave access to alice, bob, carol"
 121     git push
 122
 123 When the push completes, gitolite will add the new users to
 124 `~/.ssh/authorized_keys` on the server, as well as create a new, empty, repo
 125 called "foo".
 126
 127 ## help for your users
 128
 129 Once a user has sent you their public key and you have added them as
 130 specified above and given them access, you have to tell them what URL to
 131 access their repos at.  This is usually "git clone git@host:reponame"; see
 132 man git-clone for other forms.
 133
 134 **NOTE**: again, if they are asked for a password, something is wrong.
 135
 136 If they need to know what repos they have access to, they just have to run
 137 "ssh git@host info".
 138
 139 ## access rule examples
 140
 141 Gitolite's access rules are very powerful.  The simplest use was already
 142 shown above.  Here is a slightly more detailed example:
 143
 144     repo foo
 145         RW+                     =   alice
 146         -   master              =   bob
 147         -   refs/tags/v[0-9]    =   bob
 148         RW                      =   bob
 149         RW  refs/tags/v[0-9]    =   carol
 150         R                       =   dave
 151
 152 Here's what these example rules say:
 153
 154   * alice can do anything to any branch or tag -- create, push,
 155     delete, rewind/overwrite etc.
 156
 157   * bob can create or fast-forward push any branch whose name does
 158     not start with "master" and create any tag whose name does not
 159     start with "v"+digit.
 160
 161   * carol can create tags whose names start with "v"+digit.
 162
 163   * dave can clone/fetch.
 164
 165 Please see the main documentation linked above for all the gory details, as
 166 well as more features and examples.
 167
 168 ## groups
 169
 170 Gitolite allows you to group users or repos for convenience.  Here's an
 171 example that creates two groups of users:
 172
 173     @staff      =   alice bob carol
 174     @interns    =   ashok
 175
 176     repo secret
 177         RW      =   @staff
 178
 179     repo foss
 180         RW+     =   @staff
 181         RW      =   @interns
 182
 183 Group lists accumulate.  The following two lines have the same effect as
 184 the earlier definition of @staff above:
 185
 186     @staff      =   alice bob
 187     @staff      =   carol
 188
 189 You can also use group names in other group names:
 190
 191     @all-devs   =   @staff @interns
 192
 193 Finally, @all is a special group name that is often convenient to use if
 194 you really mean "all repos" or "all users".
 195
 196 ## commands
 197
 198 Users can run certain commands remotely, using ssh.  Running
 199
 200     ssh git@host help
 201
 202 prints a list of available commands.
 203
 204 The most commonly used command is "info".  All commands respond to a
 205 single argument of "-h" with suitable information.
 206
 207 If you have shell on the server, you have a lot more commands available to
 208 you; try running "gitolite help".
 209
 210 <!-- --------------------------------------------------------------------- -->
 211
 212 ## LICENSE
 213
 214 # contact and support
 215
 216 Please see <http://gitolite.com/gitolite/#contact> for mailing list and IRC
 217 info.
 218
 219 # license
 220
 221 The gitolite software is copyright Sitaram Chamarty and is licensed under the
 222 GPL v2; please see the file called COPYING in the source distribution.
 223
 224 Please see <http://gitolite.com/gitolite/#license> for more.
 225
 226 >   -------------------------------------------------------------------------
 227
 228 >   **NOTE**: GIT is a trademark of Software Freedom Conservancy and my use of
 229 >   "Gitolite" is under license.
 230
 231 >   -------------------------------------------------------------------------