gitolite/doc/emergencies.mkd
Sitaram Chamarty de40461d9a document overhaul
- explicit 'list' gives way to mindmap, ...
  - 'fm2mt.pl' to produce master-toc.mkd from the mindmap
  - mkdoc no longer ignores master-toc.mkd, calls fm2mt.pl itself

and LOTS of changes to the actual docs
2012-04-05 21:42:22 +05:30

191 lines
6.9 KiB
Markdown

# 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) 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>