gitolite/doc/emergencies.mkd

# help for emergencies

----

"Don't Panic!"

----

## #lost-key lost admin key/access

If you lost your gitolite **admin** key or access, here's what you do.  We'll
assume your username is 'alice'.

  * Make yourself a new keypair and copy the public key to the server as
    'alice.pub'.

  * Log on to the server, and run `gitolite setup -pk alice.pub`.

That's it; the new alice.pub file replaces whatever existed in the repo
before.

## #bypass bypassing gitolite

You may have lost access because of a conf file error, in which case the above
trick won't help.  What you want is to make changes to the repo (or perhaps
just rewind) and push that.  Here's how to do that:

  * Log on to the server.

  * Clone the admin repo using the full path: `git clone
    $HOME/repositories/gitolite-admin.git temp`.

  * Make whatever changes you want -- add/replace a key, 'git revert' or 'git
    reset --hard' to an older commit, etc.  Anything you need to fix the
    problem, really.

  * Run `gitolite push` (or possibly `gitolite push -f`).  Note that's
    'gitolite push', not 'git push'.

<font color="red">
**NOTE**: gitolite does **no access checking** when you do this!
</font>

## #clean cleaning out a botched install

If you've read the [files involved in gitolite][files] page, you probably know
the answer, but here's a list of files you should blow away.

  * **Gitolite sources** -- can be found by running `which gitolite`.  If it's
    a symlink, go to its target directory.

  * **Gitolite admin directory** -- `$HOME/.gitolite`.  Save the 'logs'
    directory if you want to preserve them for any reason.

  * **The rc file** -- `$HOME/.gitolite.rc`.  If you made any changes to it
    you can save it as some other name instead of deleting it.

  * **The gitolite-admin repo** -- `$HOME/repositories/gitolite-admin.git`.
    You can clone it somewhere to save it before blowing it away if you wish.

  * **Git repositories** -- `$HOME/repositories`.  The install process will
    not touch any existing repos except 'gitolite-admin.git', so you do not
    have to blow away (or move) your work repos to fix a botched install.

    Only when you update the conf to include those repos and push the changes
    will those repos be touched.  And even then all that happens is that the
    update hook, if any, is replaced with gitolite's own hook.

  * **Ssh stuff** -- exercise caution when doing this, but in general it
    should be safe to delete all lines between the "gitolite start" and
    "gitolite end" markers in `$HOME/.ssh/authorized_keys`.

    Gitolite does not touch any other files in the ssh directory.

## #ce common errors

  * `WARNING: keydir/<yourname>.pub duplicates a non-gitolite key, sshd will ignore it`

    You used a key that is already set to give you shell access.  You cannot
    use the same key to get shell access as well as access gitolite repos.

    Solution: use a different keypair for gitolite.  There's a slightly longer
    discussion in the [setup][] page.  Also see [why bypassing causes a
    problem][ybpfail] and both the documents in [ssh][] for background.

  * `Empty compile time value given to use lib at hooks/update line 6`

    (followed by `Can't locate Gitolite/Hooks/Update.pm in @INC` a couple of
    lines later).

    You're bypassing gitolite.  You cloned the repo using the full path (i.e.,
    including the `repositories/` prefix), either directly on the server, or
    via ssh but with a key that gives you **shell** access.

    Solution: same as for the previous bullet.

    NOTE: If you really *must* do it, and this is a one-time thing, you can
    try `gitolite push` instead of `git push`.  **BUT**... this defeats all
    gitolite access control, so if you're going to do this often, maybe you
    don't need gitolite!

## #ue uncommon errors

  * `WARNING: split conf not set, gl-conf present for <repo>`

    (Case 1) you copied a bare repo ("repo.git") from another g3 site (or g2
    with `GL_BIG_CONFIG` on).  Then you pushed a change to "gitolite.conf" or
    ran certain server-side commands without adding the repo to the conf.

    Conversely, you removed "repo" from "gitolite.conf" but did not remove the
    actual "repo.git" on disk.

    (Case 2) This can also happen if you changed something like this

        repo foo
            ...<some rules>...

    to this

        @grp = foo
        repo @grp
            ...<some rules>...

    Also, even running `gitolite setup` will not fix this.

    The root cause is an internal consistency check that I do not wish to
    disable or subvert.  It is there for a reason, and I would prefer a
    warning that a human can investigate.

    If you're sure the reasons are one of the two above, you can either add
    the repo to the conf file in case 1, or manually remove the gl-conf file
    from the repo.git directory in case 2.

    Either way, run `gitolite setup` afterwards to make sure things are in
    good shape.

    If you think neither of those is the cause, email me.

## #ngp things that are not gitolite problems

There are several things that appear to be gitolite problems but are not.  I
cannot help with most of these (although the good folks on irc or the mailing
list -- see [contact][] -- might be able to; they certainly appear to have a
lot more patience than I do, bless 'em!)

  * **Client side software**

      * putty/plink
      * jgit/Eclipse
      * Mac OS client **or** server
      * putty/plink
      * windows as a server
      * ...probably some more I forgot; will update this list as I remember...
      * did I mention putty/plink?

  * **Ssh**

    The *superstar* of the "not a gitolite problem" category is actually ssh.

    Surprised?  It is so common that it has [its own document][auth] to tell
    you why it is *not* a gitolite problem, while [another one][ssh] tries to
    help you anyway!

    Everything I know is in that latter link.  Please email me about ssh ONLY
    if you find something wrong or missing in those documents.

  * **Git**

    I wish I had a dollar for each time someone did a *first push* on a new
    repo, got an error because there were "no refs in common (etc.)", and
    asked me why gitolite was not allowing the push.

    Gitolite is designed to look like just another bare repo server to a
    client (except requiring public keys -- no passwords allowed).  It is
    *completely transparent* when there is no authorisation failure (i.e.,
    when the access is allowed, the remote client has no way of knowing
    gitolite was even installed!)

    Even "on disk", apart from reserving the `update` hook for itself,
    gitolite does nothing to your bare repos unless you tell it to (for
    example, adding 'gitweb.owner' and such to the config file).

    BEFORE you think gitolite is the problem, try the same thing with a normal
    bare repo.  In most cases you can play with it just by doing something
    like this:

        mkdir /tmp/throwaway
        cd    /tmp/throwaway
        git clone --mirror <some repo you have a URL for> bare.git
        git clone bare.git worktree
        cd worktree
        <...try stuff>