From d27af37d21bcfd9ccc212743d3d3f1a004a25787 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Fri, 28 Aug 2009 19:09:31 +0530 Subject: [PATCH] faq-tips-etc: completely revamped; big "differences from gitosis" section, etc --- doc/3-faq-tips-etc.mkd | 113 +++++++++++++++++++++++++++++++++++------ 1 file changed, 97 insertions(+), 16 deletions(-) diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd index ed3754e..bd66101 100644 --- a/doc/3-faq-tips-etc.mkd +++ b/doc/3-faq-tips-etc.mkd @@ -1,5 +1,14 @@ # assorted faqs, tips, and notes on gitolite +In this document: + + * errors, warnings, notes... + * differences from gitosis + * one user, many keys + * who am I? + * cool ideas I want feedback on + * developer specific branches + ### errors, warnings, notes... * cloning an empty repo is only possible with clients greater than 1.6.2. @@ -13,26 +22,98 @@ * once in a while, if you're feeling particularly BOFH-ish, take a look at `$GL_ADMINDIR/log` :-) -### special cases +### differences from gitosis + +Apart from the big ones listed in the top level README, and subjective ones +like "better config file format", there are some small, but significant and +concrete, differences from gitosis. + +#### built-in logging + +...just in case of emergency :-) + +Let's say you gave a dev the right to rewind a branch and he went and rewound +it all the way, or pushed something drastically different on it. Now you need +to recover the commit that got wiped out. + +If you'd remembered to `git config core.logAllRefUpdates` for that repo, or +globally, you'd be fine -- the reflog will tell you. Otherwise you'd be left +grubbing around in `git fsck --unreachable` a bit :-( + +And even if you recover the correct commit, you'll never know *who* did it -- +not unless you add a one-line patch to gitosis, plus a `post-receive` hook to +every repository. + +With gitolite, there's a log file in `$GL_ADMINDIR` that contains lines like +this [I have abbreviated the SHAs for brevity in this document; the actual log +file will have all 40 characters]: + + +: username reponame refs/heads/branchname d0188d1 c5c00b6 + +The "+" at the start indicates a non-fast forward update, in this case from +d0188d1 to c5c00b6 So d0188d1 is the one to restore! Can it get easier? #### one user, many keys -Sometimes the same user needs to access the server from differnt machines -(like a desktop and a laptop, for instance). Gitolite needs to be given all -these public keys, but associate *all* of them with the same user. +I have a laptop and a desktop I need to access the server from. I have +different private keys on them, but as far as gitolite is concerned both of +them should be treated as "sitaram". How does this work? -Recall from the "admin" document that each "user" has one public key file -called "user.pub", which seems to imply a one-to-one match. +In gitosis, the admin creates a single "sitaram.pub" containing one line for +each of my pubkeys. In gitolite, we keep them separate: "sitaram@laptop.pub" +and "sitaram@desktop.pub". The part before the "@" is the username, so +gitolite knows these two keys belong to the same person. -But this is not strictly true -- gitolite allows a *filename* to have a small -"location" piece attached to it. So you can have "sitaram@laptop.pub" and -"sitaram@desktop.pub", for instance, and they'll all be treated as keys for -"sitaram". Just add both the files to "keydir/", and use the username -"sitaram" (*without* the "@location" part) in your `gitolite.conf` file. +I think this is easier to maintain if you have to delete or change one of +those keys. -Advantages: if a user reports *one of his keys* is lost or needs replacing, -it's easy to remove or replace just that. +#### who am I? -(Contrast with gitosis, which keeps multiple entries in the same "user.pub" -file. Deleting or changing one of the keys involves editing the file and -figuring out which key is the right one!) +As a developer, I send a file called "id_rsa.pub" to the gitolite admin. He +would rename it to "sitaram.pub" and put it in the key directory. Then he'd +add "sitaram" to the config file for the repos which I have access to. + +But he could have called me "foobar" instead of "sitaram" -- as long as he +uses it consistently, it'll all work the same and look the same to me, because +the public key is all that matters. + +So do I have no reason to know what the admin named me? Well -- maybe (see +next section for one possible use). Anyway how do I find out? + +In gitolite, it's simple: just ask nicely :-) + + $ ssh git@my.gitolite.server + PTY allocation request failed on channel 0 + no SSH_ORIGINAL_COMMAND? I'm not a shell, sitaram! + +### cool ideas + +#### developer specific branches + +So I know what gitolite calls me. Big deal... who cares? + +Here is a cool idea: allow me to create, rewind, or delete any branch whose +full name matches this pattern: + + $PERSONAL_BRANCH_PREFIX/sitaram-.* + +The admin could set `$PERSONAL_BRANCH_PREFIX` in the rc file and communicate +this to all users. It could be something like `refs/heads/personal`, which +means all such branches will show up in `git branch` lookups and `git clone` +will fetch them. Or he could use, say, `refs/personal`, which means it won't +show up in any normal "branch-y" commands and stuff, and generally be much +less noisy. + +Yes, I know git is all about allowing private branches, but in a corporate +environment it's not always possible to pull from a co-worker, for the same +reasons you don't have anonymous access (like the git:// protocol). A normal +developer workstation cannot do authentication, so how would they know who's +pulling? This is a perfect way to share code *without* cluttering the global +namespace, and each developer controls his/her own set of branches! + +The amount of code needed? *One line!* I'll spend about 3x more on declaring +and initialising the new variable, and 30x more on documenting it :-) + +**That** is how neatly gitolite is designed... + +/me pats himself on the back ;-)