gitolite/doc/users.mkd

# adding and removing users

Strictly speaking, gitolite doesn't know where users come from.  If that
surprises you, read [this][auth].  However, gitolite does help with ssh-based
authentication, so here's some info on adding and removing users.

>   ----

>   *WARNING: Do NOT add users directly on the server.  Clone the
>   'gitolite-admin' repo to your workstation, make changes to it, then add,
>   commit, and push.  When the push hits the server, the server "acts" upon
>   your changes.*

>   ----

All operations are in a clone of the gitolite-admin repo.

To **add** a user, say Alice, obtain her public key (typically
`$HOME/.ssh/id_rsa.pub` on her workstation), copy it to `keydir` with the user
name as the basename (e.g., 'alice.pub' for user alice), then `git add
keydir/alice.pub`.  (All keys files must have names ending in ".pub", and must
be in openssh's default format).

To **remove** a user, `git rm keydir/alice.pub`.

In both cases, you must commit and push.  On receiving the push, gitolite will
carry out the changes specified.

The user name is simply the base name of the public key file name.  So
'alice.pub', 'foo/alice.pub' and 'bar/alice.pub', all resolve to user "alice".

## #multi-key multiple keys per user

The simplest and most understandable is to put their keys in different
subdirectories, (alice.pub, home/alice.pub, laptop/alice.pub, etc).

### old style multi-keys

There is another way that involves creating key files like `alice@home.pub`
and `alice@laptop.pub`, but there is a complication because gitolite also
allows *full email addresses* as user names.  (I.e., `sitaramc@gmail.com.pub`
denotes the user called `sitaramc@gmail.com`).

This older method of enabling multi-keys was developed to deal with that.  It
will continue to work and be supported in *code*, simply because I prefer it.
But I will not accept questions or doc patches for it, because it seems it is
too difficult to understand for a lot of people.  This table of sample pubkey
filenames and the corresponding derived usernames is all you get:

  * plain username, no multikey

        sitaramc.pub                            sitaramc

  * plain username, with multikeys

        sitaramc@laptop.pub                     sitaramc
        sitaramc@desktop.pub                    sitaramc

  * email address as username, no multikey

        sitaramc@gmail.com.pub                  sitaramc@gmail.com

  * email address as username, with multikeys

        sitaramc@gmail.com@laptop.pub           sitaramc@gmail.com
        sitaramc@gmail.com@desktop.pub          sitaramc@gmail.com