docs/user.mkd

   1 # the users' view
   2
   3 ----
   4
   5 This page talks about what gitolite looks like to non-admins, and the commands
   6 and features available to them.
   7
   8 # accessing gitolite
   9
  10 The most common setup is based on ssh, where your admin asks you to send him
  11 your public key, and uses that to setup your access.
  12
  13 Your actual access is either a git command (like `git clone git@server:reponame`,
  14 or an ssh command (like `ssh git@server info`).
  15
  16 Note that you do *not* get a shell on the server -- the whole point of
  17 gitolite is to prevent that!
  18
  19 **Note to people who think gitolite requires or can only handle a specific
  20 syntax for the URL**: Gitolite is designed in such a way that, unless there is
  21 an access violation, the *client* need not even *know* that something called
  22 gitolite is sitting between it and git on the server.  In particular, this
  23 means *any* URL syntax listed in 'man git-clone' for ssh and/or http will
  24 work.  The only things to note are:
  25
  26   * In ssh mode, you *must* use key-based authentication (i.e., passwords
  27     won't work; see the two pages linked from the [ssh](ssh) page for why).
  28   * The path of the repo is what you put into the conf file (e.g., "testing",
  29     and not "repositories/testing" or "/home/git/repositories/testing" or
  30     such).  A good rule of thumb is to use the exact name the `info` command
  31     (see below) shows you.
  32   * The ".git" at the end is optional for **git** commands (i.e., you can use
  33     "testing.git" instead of "testing" for clone, fetch, push, etc., if you
  34     like) but **gitolite** commands in general (see below) will not like the
  35     additional ".git" at the end.
  36
  37 # the info command
  38
  39 The only command that is *always* available to every user is the `info`
  40 command (run `ssh git@host info -h` for help), which tells you what version of
  41 gitolite and git are on the server, and what repositories you have access to.
  42 The list of repos is very useful if you have doubts about the spelling of some
  43 new repo that you know was setup.
  44
  45 # normal and wild repos
  46
  47 Gitolite has two kinds of repos.  Normal repos are specified by their full
  48 names in the config file.  "Wildcard" repos are specified by a regex in the
  49 config file.  Try the [`info` command][info] and see if it shows any lines
  50 that look like regex patterns, (with a "C" permission).
  51
  52 [info]: user#the-info-command
  53
  54 If you see any, it means you are allowed to create brand new repos whose names
  55 fit that regex.  Normally, you create such repos simply by cloning them or
  56 pushing to them -- gitolite automatically creates the repo on the server side.
  57 (If your site is different, your admin will tell you).
  58
  59 When you create such a repo, your "ownership" of it (as far as gitolite is
  60 concerned) is automatically recorded by gitolite.
  61
  62 # other commands
  63
  64 ## set/get additional permissions for repos you created
  65
  66 The gitolite config may have several permissions lines for your repo, like so:
  67
  68 ```gitolite
  69 repo pub/CREATOR/..*
  70     C       =   ...some list of users allowed to create repos...
  71     RW+     =   CREATOR
  72     RW      =   user1 user2
  73     R       =   user3
  74 ```
  75
  76 If that's all it had, you really can't do much.  Any changes to access must be
  77 done by the administrator.  (Note that "CREATOR" is a reserved word that gets
  78 expanded to your userid in some way, so the admin can literally add just the
  79 first three lines, and *every* user listed in the second line (or *every
  80 authenticated user*, if you specified `@all` there) has his own personal repo
  81 namespace, starting with `pub/<username>/`).
  82
  83 To give some flexibility to users, the admin could add rules like this:
  84
  85 ```gitolite
  86     RW      =   WRITERS
  87     R       =   READERS
  88 ```
  89
  90 <span class="gray">(he could also add other [roles](wild#roles) but then he
  91 needs to read the documentation).</span>
  92
  93 Once he does this, you can then use the `perms` command (run `ssh git@host perms -h`
  94 for help) to set permissions for other users by specifying which
  95 users are in the list of "READERS", and which in "WRITERS".
  96
  97 If you think of READERS and WRITERS as "roles", it will help.  You can't
  98 change what access a role has, but you *can* say which users have that role.
  99
 100 !!! note "Note:"
 101
 102     There isn't a way for you to see the actual rule list unless you're given
 103     read access to the special 'gitolite-admin' repo.  Sorry.  The idea is
 104     that your admin will tell you what "roles" he added into rules for your
 105     repos, and what permissions those roles have.
 106
 107 ## adding a description to repos you created
 108
 109 The `desc` command is extremely simple.  Run `ssh git@host desc -h` for help.
 110
 111 # "site-local" commands
 112
 113 The main purpose of gitolite is to prevent you from getting a shell.  But
 114 there are commands that you often need to run on the server (i.e., cannot be
 115 done by pushing something to a repo).
 116
 117 To enable this, gitolite allows the admin to setup scripts in a special
 118 directory that users can then run.  Gitolite comes with a set of working
 119 scripts that your admin may install, or may use as a starting point for his
 120 own, if he chooses.
 121
 122 Think of these commands as equivalent to those in `COMMAND_DIR` in `man git-shell`.
 123
 124 You can get a list of available commands by running `ssh git@host help`.
 125
 126 # "personal" branches
 127
 128 "personal" branches are great for environments where developers need to share
 129 work but can't directly pull from each other (usually due to either a
 130 networking or authentication related reason, both common in corporate setups).
 131
 132 Personal branches exist **in a sub-tree** of the `ref/heads/[...]` hierarchy.
 133 The syntax is
 134
 135 ```gitolite
 136     RW+ personal/USER/  =   @userlist
 137 ```
 138
 139 where (a) the "personal" can be anything you like, but cannot be empty, (b) the
 140 "/USER/" part is **necessary (including both slashes)**, and (c) the trailing
 141 slash can be optionally followed by additional restrictions on the ref name.
 142
 143 A user "alice" (if she's in the userlist) can then push any branches inside
 144 `personal/alice/` (i.e., she can push `personal/alice/foo` and
 145 `personal/alice/bar`, but NOT `personal/alice`).  As another example
 146 `personal/USER/[a-zA-Z0-9_]+$` would mean that alice can create
 147 `personal/alice/foo`, but not `personal/alice/foo/bar`, because a `/` is not
 148 allowed by the expression following the `/USER/`.
 149
 150 (Background: at runtime the "USER" component will be replaced by the name of
 151 the invoking user.  Access is determined by the right hand side, as usual).
 152
 153 Compared to using arbitrary branch names on the same server, this:
 154
 155   * Reduces namespace pollution by corralling all these ad hoc branches into
 156     the "personal/" namespace.
 157   * Reduces branch name collision by giving each developer her own
 158     sub-hierarchy within that.
 159   * Removes the need to think about access control, because a user can push
 160     only to his own sub-hierarchy.
 161