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'.

**NOTE**: gitolite does **no access checking** when you do this!

#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) This can happen if you have a bare repo (i.e., some repo.git directory) copied from g2 with GL_BIG_CONFIG on, and you pushed a change to the conf or ran certain commands before adding the newly added repo to the conf file.

  (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>