user.mkd

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