(minor) nagp.mkd
This commit is contained in:
Sitaram Chamarty
parent
30d46947ab
commit
bee5a11d4b
287
doc/nagp.mkd
Normal file
287
doc/nagp.mkd
Normal file
|
|
@ -0,0 +1,287 @@
|
||||||
|
# ...not a gitolite problem!
|
||||||
|
|
||||||
|
Subtitle: Unix, ssh, git, and gitolite -- recognising the boundaries
|
||||||
|
|
||||||
|
**Warning**: Most of this is technical, but some of it is definitely
|
||||||
|
subjective opinion.
|
||||||
|
|
||||||
|
----
|
||||||
|
|
||||||
|
In this document:
|
||||||
|
|
||||||
|
* <a href="#_background">background</a>
|
||||||
|
* <a href="#_ssh">ssh</a>
|
||||||
|
* <a href="#_git">git</a>
|
||||||
|
* <a href="#_windows">windows</a>
|
||||||
|
* <a href="#_apple">apple</a>
|
||||||
|
* <a href="#_just_say_NO_">just say NO!</a>
|
||||||
|
* <a href="#_behind_my_back">behind my back</a>
|
||||||
|
* <a href="#_that_s_outrageous">that's outrageous</a>
|
||||||
|
|
||||||
|
----
|
||||||
|
|
||||||
|
<a name="_background"></a>
|
||||||
|
|
||||||
|
### background
|
||||||
|
|
||||||
|
More and more people are being tasked with creating a "server" environment for
|
||||||
|
git, (and thus being forcibly introduced to gitolite), before they've had a
|
||||||
|
chance to know git (or even Unix) well enough. As a result, I often get
|
||||||
|
questions that have **nothing** to do with gitolite, because people don't know
|
||||||
|
where the boundaries are.
|
||||||
|
|
||||||
|
Here're some facts about gitolite:
|
||||||
|
|
||||||
|
* gitolite runs on the server. To the client it looks just like any other
|
||||||
|
ssh-based URL that is using public keys.
|
||||||
|
|
||||||
|
* once you connect, it looks just like any other [bare repo][bare] on a
|
||||||
|
server for normal git operations (clone, fetch, push). Users won't even
|
||||||
|
*know* it exists if they do only what they're allowed to. (I.e., it
|
||||||
|
becomes visible only when it has to deny access for some operation)
|
||||||
|
|
||||||
|
* even "on disk", except for reserving the `update` hook for its own
|
||||||
|
purposes and possibly a couple of extra files, the contents of a
|
||||||
|
gitolite-managed bare repo are the same as a normal bare repo.
|
||||||
|
|
||||||
|
A good short term measure is to read this [simple git session][sgs] for
|
||||||
|
insights into the relationship between the "server" and the "client" in git.
|
||||||
|
That might help with some of the problems described in this document.
|
||||||
|
|
||||||
|
[bare]: http://sitaramc.github.com/concepts/0-terminology.html#working_tree_repository_bare_repository
|
||||||
|
[sgs]: http://sitaramc.github.com/1-basic-usage/simple-git-session.html
|
||||||
|
|
||||||
|
<a name="_ssh"></a>
|
||||||
|
|
||||||
|
### ssh
|
||||||
|
|
||||||
|
Let's get this out of the way first. The *superstar* of the "not a gitolite
|
||||||
|
problem" category is actually ssh.
|
||||||
|
|
||||||
|
Surprised? It is so common that it has [its own document][aa] to tell you why
|
||||||
|
it is *not* a gitolite problem, while [another one][sts] tries to help you
|
||||||
|
anyway!
|
||||||
|
|
||||||
|
[aa]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html
|
||||||
|
[sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
|
||||||
|
[hc]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_hook_chaining
|
||||||
|
|
||||||
|
<a name="_git"></a>
|
||||||
|
|
||||||
|
### git
|
||||||
|
|
||||||
|
* first push to a new repo
|
||||||
|
|
||||||
|
Even if the error message said "the remote end hung up unexpectedly", this
|
||||||
|
is not a gitolite problem. If you read the full message, it will probably
|
||||||
|
be something like this:
|
||||||
|
|
||||||
|
No refs in common and none specified; doing nothing.
|
||||||
|
Perhaps you should specify a branch such as 'master'.
|
||||||
|
fatal: The remote end hung up unexpectedly
|
||||||
|
error: failed to push some refs to '/tmp/tmp-repos/bare.git'
|
||||||
|
|
||||||
|
(To be fair, this message is still not clear enough; even a careful reader
|
||||||
|
might end up trying `git push master` instead of `git push origin
|
||||||
|
master`.)
|
||||||
|
|
||||||
|
* client-side versus server-side hooks
|
||||||
|
|
||||||
|
Just because you saw something in gitolite's docs about hooks, it doesn't
|
||||||
|
mean gitolite can make a "post-checkout" hook work!
|
||||||
|
|
||||||
|
You need to read man githooks again to understand the difference between
|
||||||
|
hooks that run on your local repo in response to local commands (like
|
||||||
|
commit, checkout), and remote hooks that run on the server in response to
|
||||||
|
a client-initiated operation (like push).
|
||||||
|
|
||||||
|
An equally wrong expectation is that a clone or a pull will also bring
|
||||||
|
along hooks from the server! Sorry, but there is nothing in git that
|
||||||
|
allows the *server* to do something on the *client* -- if there were, it
|
||||||
|
would be a huge security issue.
|
||||||
|
|
||||||
|
What you can do in gitolite is to write yourself a hook that checks every
|
||||||
|
commit in a push for compliance and rejects the push (*all* the commits in
|
||||||
|
the push, mind!) if it doesn't comply. However, other than telling you
|
||||||
|
how to get your hook to trigger, the actual code in that hook is out of
|
||||||
|
scope for me.
|
||||||
|
|
||||||
|
* Jenkins integration
|
||||||
|
|
||||||
|
I don't know much about CI systems, but I'm pretty sure they run off of
|
||||||
|
some hook or other, but gitolite may already be using those hooks. The
|
||||||
|
section on hook chaining [here][hc] shows you how to run your own hooks.
|
||||||
|
|
||||||
|
In short, CI integration is no more a gitolite problem than any other
|
||||||
|
purpose for which git's hooks can be used.
|
||||||
|
|
||||||
|
<a name="_windows"></a>
|
||||||
|
|
||||||
|
### windows
|
||||||
|
|
||||||
|
I'm *interested* in making sure it works fine with Windows, simply because I
|
||||||
|
have colleagues at work who use it. But that doesn't mean I can help you; I
|
||||||
|
just don't know enough to help you. (And if you even breathe the words
|
||||||
|
"putty" or "plink" I will totally tune you out!)
|
||||||
|
|
||||||
|
I do have people using it happily on Windows with Eclipse, Visual Studio, and
|
||||||
|
God alone knows what else, so I know it *can* (be made to) work.
|
||||||
|
|
||||||
|
So, hang in there... it'll all work out eventually.
|
||||||
|
|
||||||
|
<a name="_apple"></a>
|
||||||
|
|
||||||
|
### apple
|
||||||
|
|
||||||
|
Weirdly enough, this is the one thing that Steve Ballmer and I probably agree
|
||||||
|
on, so I won't elaborate on that ;-)
|
||||||
|
|
||||||
|
It seems to me though, that many recent reports of "weird" behaviour reported
|
||||||
|
have come from Macs. Yet another reason for me to back off with an apology.
|
||||||
|
|
||||||
|
<a name="_just_say_NO_"></a>
|
||||||
|
|
||||||
|
### just say NO!
|
||||||
|
|
||||||
|
These are the things I won't do, for various reasons, mostly technical, with a
|
||||||
|
smattering of some subjective stuff. If you've been hit by one of these, and
|
||||||
|
disagree with me -- well that's why gitolite is GPL. As long as you satisfy
|
||||||
|
the GPL, you can simply "fork off" ;-)
|
||||||
|
|
||||||
|
* using a database backend
|
||||||
|
|
||||||
|
Someone wanted help rewriting gitolite to use a database instead of a perl
|
||||||
|
hash.
|
||||||
|
|
||||||
|
I think that's a very bad idea. Show me an install where gitolite does
|
||||||
|
not scale and I'll fix it without using a damn database. I *chose* the
|
||||||
|
perl hash very deliberately and for very specific reasons; using a DB
|
||||||
|
would kill all that.
|
||||||
|
|
||||||
|
* symlinks within `REPO_BASE`
|
||||||
|
|
||||||
|
Someone wanted to put the actual repos somewhere else and create a symlink
|
||||||
|
to them inside gitolite's `REPO_BASE`.
|
||||||
|
|
||||||
|
No. Gitolite assumes all of `REPO_BASE` is in its control, and nothing
|
||||||
|
else outside is (barring the admin directory `~/.gitolite` and the rc file
|
||||||
|
`~/.gitolite.rc`).
|
||||||
|
|
||||||
|
You could argue that this is secure enough if the admin knows what he is
|
||||||
|
doing, but I'm not buying that. Some odd screwup involving symlinks will
|
||||||
|
show up some day and gitolite will get blamed.
|
||||||
|
|
||||||
|
* deleting environment variables copied from client session
|
||||||
|
|
||||||
|
This same guy wanted me to add code to delete certain environment
|
||||||
|
variables at startup because "the openssh servers in the linux
|
||||||
|
distribution that [he] use[s], are configured to copy `GIT_*` variables to
|
||||||
|
the remote session".
|
||||||
|
|
||||||
|
This is wrong on so many levels it's almost plonk-able!
|
||||||
|
|
||||||
|
* using `cp` instead of `ln`
|
||||||
|
|
||||||
|
Guy has an NTFS file system mounted on Linux. So... no symlinks (an NTFS
|
||||||
|
file system on Windows works fine because msysgit/cygwin manage to
|
||||||
|
*simulate* them. NTFS mounted on Linux won't do that!)
|
||||||
|
|
||||||
|
He wanted all the symlink stuff to be replaced by copies.
|
||||||
|
|
||||||
|
No. Way.
|
||||||
|
|
||||||
|
* non-bare repos on the server
|
||||||
|
|
||||||
|
Some guy gave me a complicated spiel about git-svn not liking bare repos
|
||||||
|
or whatever. I tuned off at the first mention of those 3 letters so I
|
||||||
|
don't really know what the actual problem was.
|
||||||
|
|
||||||
|
But it doesn't matter. Even if someone (Ralf H) had not chipped in with a
|
||||||
|
workable solution, I still would not do it. A server repo should be bare.
|
||||||
|
Period.
|
||||||
|
|
||||||
|
<a name="_behind_my_back"></a>
|
||||||
|
|
||||||
|
#### behind my back
|
||||||
|
|
||||||
|
Some of the "Just say NO" items are from situations where someone or something
|
||||||
|
changes stuff behind gitolite's back. I am particularly unsympathetic to this
|
||||||
|
sort of thing.
|
||||||
|
|
||||||
|
* incomplete ownership of `REPO_BASE`
|
||||||
|
|
||||||
|
This guy had a repo-base directory where not all of the files were owned
|
||||||
|
by the git user. As a result, some of the hooks did not get created. He
|
||||||
|
claimed my code should detect OS-permissions issues while it's doing its
|
||||||
|
stuff.
|
||||||
|
|
||||||
|
No. I refuse to have the code constantly look over its shoulder making
|
||||||
|
sure fundamental assumptions are being met.
|
||||||
|
|
||||||
|
* empty template directory
|
||||||
|
|
||||||
|
(See man git-init for what a template directory is).
|
||||||
|
|
||||||
|
The same guy with the symlinks and the environment variables (so this is
|
||||||
|
his third appearance in this list!) had an empty template directory
|
||||||
|
because he "does not like to have sample hooks in every repository". So
|
||||||
|
naturally, the hooks directory does not get created when you run a `git
|
||||||
|
init`. He expects gitolite to compensate for it.
|
||||||
|
|
||||||
|
Granted, it's only a 1-line change. But again, this falls under
|
||||||
|
"constantly looking over your shoulder to double check fundamental
|
||||||
|
assumptions". Where does it end?
|
||||||
|
|
||||||
|
* per-repo umask setting
|
||||||
|
|
||||||
|
Some people believe that gitolite should have code to compensate for a
|
||||||
|
"potential" failure of gitweb or httpd to restrict access as designed.
|
||||||
|
|
||||||
|
Sorry. Not in "core" at least. This is yet another of those "constantly
|
||||||
|
looking over your shoulder" examples. Why should it be gitolite's problem
|
||||||
|
to compensate if gitweb or httpd misbehave? Yes, I know all about layers
|
||||||
|
of security and defense in depth, thank you but no.
|
||||||
|
|
||||||
|
<font color="gray">
|
||||||
|
|
||||||
|
> I gave them a solution that involves adding `config
|
||||||
|
> core.sharedRepository = 0750` in the gitolite.conf file for those
|
||||||
|
> repos, then doing a one-time fixup for newly created repos. But they
|
||||||
|
> decided they needed to patch gitolite and they're going with it.
|
||||||
|
|
||||||
|
> I'm not too worried. These guys ran a HEAVILY patched gitosis for
|
||||||
|
> years; they're probably used to it.
|
||||||
|
|
||||||
|
</font>
|
||||||
|
|
||||||
|
<a name="_that_s_outrageous"></a>
|
||||||
|
|
||||||
|
### that's outrageous
|
||||||
|
|
||||||
|
This section is for really outrageous stuff.
|
||||||
|
|
||||||
|
* clearing out a repo the long/wrong way
|
||||||
|
|
||||||
|
This guy tells me he often needs to clear out a repo. How? He first
|
||||||
|
manually deletes the repo on the server, then pushes a dummy commit to the
|
||||||
|
admin repo to let gitolite re-create it.
|
||||||
|
|
||||||
|
Of course, this second step is "annoying" so he mailed me and told me
|
||||||
|
there has to be a better way!
|
||||||
|
|
||||||
|
I asked him why he didn't try `git push -f` and he said he didn't know he
|
||||||
|
could do that. I'm NOT joking. I wish I were! (Yes, we all know that
|
||||||
|
`git push -f` is not the same as delete/re-create, but the point is that
|
||||||
|
he really didn't need it; he just assumed that's the only way to force his
|
||||||
|
commits to the remote.)
|
||||||
|
|
||||||
|
* can connect to github, can't connect to gitolite
|
||||||
|
|
||||||
|
So this mac-fan went on about his great IDE (CodeX or something) and how
|
||||||
|
it works with github but no luck with gitolite. Therefore he comes and
|
||||||
|
asks on \#gitolite. (I give him bonus points for telling people on TWO
|
||||||
|
channels that it is "THE best ide").
|
||||||
|
|
||||||
|
The actual error? "host unreachable".
|
||||||
|
|
||||||
|
In usenet terms... `*PLONK*`!
|
||||||
Loading…
Reference in a new issue