deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

(collected docfixes)

Browse source
This commit is contained in:
Sitaram Chamarty 2012-05-18 12:48:43 +05:30
parent 84d123e124
commit 6f740908bb
5 changed files with 50 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/dev-notes.mkd
View file

@ -1,5 +1,9 @@
# notes for developers # notes for developers
[[TOC]]
----
Gitolite has a huge bunch of existing features that gradually need to moved Gitolite has a huge bunch of existing features that gradually need to moved
over. Plus you may want to write your own programs to interact with it. over. Plus you may want to write your own programs to interact with it.
@ -37,7 +41,7 @@ more info.
* `gitolite git-config` to check gitolite options or git config variables * `gitolite git-config` to check gitolite options or git config variables
directly from gitolite's "compiled" output, (i.e., without looking at the directly from gitolite's "compiled" output, (i.e., without looking at the
actual `repo.git/config` file or using the `git config` command). Example actual `repo.git/config` file or using the `git config` command). Example
use: none yet. use: src/triggers/post-compile/update-gitweb-access-list.
* `gitolite query-rc` to check the value of an RC variable. Example use: * `gitolite query-rc` to check the value of an RC variable. Example use:
src/commands/desc. src/commands/desc.

10
doc/emergencies.mkd
View file

@ -103,10 +103,12 @@ the answer, but here's a list of files you should blow away.
* `WARNING: split conf not set, gl-conf present for <repo>` * `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` (Case 1) you copied a bare repo ("repo.git") from another g3 site (or g2
directory) copied from g2 with `GL_BIG_CONFIG` on, and you pushed a change with `GL_BIG_CONFIG` on). Then you pushed a change to "gitolite.conf" or
to the conf or ran certain commands *before* adding the newly added repo ran certain server-side commands without adding the repo to the conf.
to the conf file.
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 (Case 2) This can also happen if you changed something like this

14
doc/extras/glssh.mkd
View file

@ -1,4 +1,8 @@
## #glssh how gitolite uses ssh # #glssh how gitolite uses ssh
[[TOC]]
----
Although other forms of authentications exist (see the document on Although other forms of authentications exist (see the document on
[authentication versus authorisation][auth]), ssh is the one that most git [authentication versus authorisation][auth]), ssh is the one that most git
@ -15,7 +19,7 @@ gitolite to work, because you'll be attacking the wrong problem.
So please please please understand this before tearing your hair out and So please please please understand this before tearing your hair out and
blaming ***git/gitolite*** for whatever is going wrong with your setup :-) blaming ***git/gitolite*** for whatever is going wrong with your setup :-)
### ssh basics ## ssh basics
Let's start with some basics, focusing *only* on the pieces relevant to Let's start with some basics, focusing *only* on the pieces relevant to
`gitolite`. If this is not detailed enough, please use google and learn more `gitolite`. If this is not detailed enough, please use google and learn more
@ -85,7 +89,7 @@ from somewhere, or maybe buy the OReilly ssh book.
**This is the backbone of what makes gitolite work; please make sure you **This is the backbone of what makes gitolite work; please make sure you
understand this**. understand this**.
### how does gitolite use all this ssh magic? ## how does gitolite use all this ssh magic?
These are two different questions you ought to be having by now: These are two different questions you ought to be having by now:
@ -93,7 +97,7 @@ These are two different questions you ought to be having by now:
logging in as the same remote user "git". logging in as the same remote user "git".
* How does it restrict what I can do within a repository. * How does it restrict what I can do within a repository.
#### restricting shell access/distinguishing one user from another ### restricting shell access/distinguishing one user from another
The answer to the first question is the `command=` we talked about before. If The answer to the first question is the `command=` we talked about before. If
you look in the `authorized_keys` file, you'll see entries like this (I chopped you look in the `authorized_keys` file, you'll see entries like this (I chopped
@ -124,7 +128,7 @@ at its config file, and either allows or rejects the request.
But this cannot differentiate between different branches within a repo; that But this cannot differentiate between different branches within a repo; that
has to be done separately. has to be done separately.
#### restricting branch level actions ### restricting branch level actions
[If you look inside the git source tree, there's a file among the "howto"s in [If you look inside the git source tree, there's a file among the "howto"s in
there called `update-hook-example.txt`, which was the inspiration for this there called `update-hook-example.txt`, which was the inspiration for this

47
doc/extras/sts.mkd
View file

@ -1,15 +1,22 @@
## #sts ssh troubleshooting # #sts ssh troubleshooting and tips
**This document must be read in full the first time. If you start from some **This document must be read in full the first time. If you start from some
nice looking section in the middle it may not help you unless you're already nice looking section in the middle it may not help you unless you're already
an expert at ssh**. an expert at ssh**.
This document should help you troubleshoot ssh-related problems in installing This document should help you troubleshoot ssh-related problems in installing
and accessing gitolite. and accessing gitolite. It also has a section of random ssh-related tips and
tricks that gitolite can do.
### IMPORTANT -- READ THIS FIRST ----
#### caveats [[TOC]]
----
## IMPORTANT -- READ THIS FIRST
### caveats
* Before reading this document, it is **mandatory** to read and **completely * Before reading this document, it is **mandatory** to read and **completely
understand** [this][ssh], which is a very detailed look at how gitolite understand** [this][ssh], which is a very detailed look at how gitolite
@ -28,7 +35,7 @@ and accessing gitolite.
Surprised? [This][auth] might help explain better. Surprised? [This][auth] might help explain better.
#### naming conventions used ### naming conventions used
* Your workstation is the **client**. Your userid on the client does not * Your workstation is the **client**. Your userid on the client does not
matter, and it has no relation to your gitolite username. matter, and it has no relation to your gitolite username.
@ -37,7 +44,7 @@ and accessing gitolite.
this is an RPM/DEB install, the hosting user is probably called this is an RPM/DEB install, the hosting user is probably called
"gitolite", however we will use "git" in this document. "gitolite", however we will use "git" in this document.
#### taking stock -- relevant files and directories ### taking stock -- relevant files and directories
* The client has a `~/.ssh` containing a few keypairs. It may also have a * The client has a `~/.ssh` containing a few keypairs. It may also have a
`config` file. `config` file.
@ -54,7 +61,7 @@ and accessing gitolite.
* The server also has a `~/.gitolite/keydir` which contains a bunch of * The server also has a `~/.gitolite/keydir` which contains a bunch of
`*.pub` files. `*.pub` files.
#### normal gitolite key handling ### normal gitolite key handling
Here's how normal gitolite key handling works: Here's how normal gitolite key handling works:
@ -80,7 +87,7 @@ Here's how normal gitolite key handling works:
between gitolite's "marker" lines (`# gitolite start` and `# gitolite between gitolite's "marker" lines (`# gitolite start` and `# gitolite
end`). end`).
### common ssh problems ## common ssh problems
Since I'm pretty sure at least some of you didn't bother to read the Since I'm pretty sure at least some of you didn't bother to read the
"IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point "IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point
@ -121,7 +128,7 @@ background info.
does not appear to be a git repository`, and yet you are sure 'reponame' does not appear to be a git repository`, and yet you are sure 'reponame'
exists, you haven't mis-spelled it, etc. exists, you haven't mis-spelled it, etc.
### step by step ## step by step
Since I'm pretty sure at least some of you didn't bother to read the Since I'm pretty sure at least some of you didn't bother to read the
"IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point "IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point
@ -144,9 +151,9 @@ Done? OK, now the general outline for ssh troubleshooting is this:
client, instead of the default key. See [appendix 3][stsapp3] and client, instead of the default key. See [appendix 3][stsapp3] and
[appendix 4][ssh-ha]. [appendix 4][ssh-ha].
### random tips, tricks, and notes ## random tips, tricks, and notes
#### giving shell access to gitolite users ### giving shell access to gitolite users
Thanks to an idea from Jesse Keating, a single key can allow both gitolite Thanks to an idea from Jesse Keating, a single key can allow both gitolite
access *and* shell access. access *and* shell access.
@ -169,7 +176,7 @@ To do this:
Then run `gitolite compile; gitolite trigger POST_COMPILE` or push a dummy Then run `gitolite compile; gitolite trigger POST_COMPILE` or push a dummy
change to the admin repo. change to the admin repo.
#### simulating ssh-copy-id ### simulating ssh-copy-id
don't have `ssh-copy-id`? This is broadly what that command does, if you want don't have `ssh-copy-id`? This is broadly what that command does, if you want
to replicate it manually. The input is your pubkey, typically to replicate it manually. The input is your pubkey, typically
@ -192,7 +199,7 @@ typically) also must be `go-w`, but that needs root. And typically
they're already set that way anyway. (Or if they're not, you've got they're already set that way anyway. (Or if they're not, you've got
bigger problems than gitolite install not working!)] bigger problems than gitolite install not working!)]
#### problems with using non-openssh public keys ### problems with using non-openssh public keys
Gitolite accepts public keys only in openssh format. Trying to use an "ssh2" Gitolite accepts public keys only in openssh format. Trying to use an "ssh2"
key (used by proprietary SSH software) will not be a happy experience. key (used by proprietary SSH software) will not be a happy experience.
@ -206,7 +213,7 @@ be done with it, is:
then use the resulting pubkey as you normally would in gitolite. then use the resulting pubkey as you normally would in gitolite.
#### windows issues ### windows issues
On windows, I have only used msysgit, and the openssh that comes with it. On windows, I have only used msysgit, and the openssh that comes with it.
Over time, I have grown to distrust putty/plink due to the number of people Over time, I have grown to distrust putty/plink due to the number of people
@ -217,7 +224,7 @@ putty/plink, including environment variables, etc., and then try again.
Thankfully, someone contributed [this][putty]. Thankfully, someone contributed [this][putty].
### #stsapp1 appendix 1: ssh daemon asks for a password ## #stsapp1 appendix 1: ssh daemon asks for a password
> **NOTE**: This section should be useful to anyone trying to get > **NOTE**: This section should be useful to anyone trying to get
> password-less access working. It is not necessarily specific to gitolite, > password-less access working. It is not necessarily specific to gitolite,
@ -289,7 +296,7 @@ This is a quick checklist:
this file for messages matching the approximate time of your last attempt this file for messages matching the approximate time of your last attempt
to login, to see if they tell you what is the problem. to login, to see if they tell you what is the problem.
### #sshkeys-lint appendix 2: which key is which -- running sshkeys-lint ## #sshkeys-lint appendix 2: which key is which -- running sshkeys-lint
The sshkeys-lint program can be run on the server or the client. Run it with The sshkeys-lint program can be run on the server or the client. Run it with
'-h' to get a help message. '-h' to get a help message.
@ -324,7 +331,7 @@ need. Be careful:
* If you're running ssh-agent, you may have to delete (using `ssh-add -D`) * If you're running ssh-agent, you may have to delete (using `ssh-add -D`)
and re-add identities for it to pick up the renamed ones correctly. and re-add identities for it to pick up the renamed ones correctly.
#### typical cause(s) ### typical cause(s)
The admin often has passwordless shell access to `git@server` already, and The admin often has passwordless shell access to `git@server` already, and
then used that same key to get access to gitolite (i.e., copied that same then used that same key to get access to gitolite (i.e., copied that same
@ -340,7 +347,7 @@ as YourName.pub, then run `gitolite setup -pk YourName.pub` on the server.
Remember to adjust your agent identities using ssh-add -D and ssh-add if Remember to adjust your agent identities using ssh-add -D and ssh-add if
you're using ssh-agent, otherwise these new keys may not work. you're using ssh-agent, otherwise these new keys may not work.
### #stsapp3 appendix 3: ssh client may not be offering the right key ## #stsapp3 appendix 3: ssh client may not be offering the right key
* Make sure the right private key is being offered. Run ssh in very * Make sure the right private key is being offered. Run ssh in very
verbose mode and look for the word "Offering", like so: verbose mode and look for the word "Offering", like so:
@ -362,7 +369,7 @@ you're using ssh-agent, otherwise these new keys may not work.
In that case, add the key you want using `ssh-add ~/.ssh/YourName` and try In that case, add the key you want using `ssh-add ~/.ssh/YourName` and try
the access again. the access again.
### #ssh-ha appendix 4: ssh host aliases ## #ssh-ha appendix 4: ssh host aliases
(or "making git use the right options for ssh") (or "making git use the right options for ssh")
@ -398,7 +405,7 @@ way to do this, as far as I know.
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
### #ybpfail appendix 5: why bypassing gitolite causes a problem ## #ybpfail appendix 5: why bypassing gitolite causes a problem
When you bypass gitolite, you end up running your normal shell instead of the When you bypass gitolite, you end up running your normal shell instead of the
special gitolite entry point script `gitolite-shell`. special gitolite entry point script `gitolite-shell`.

3
doc/g2migr.mkd
View file

@ -242,6 +242,9 @@ put that contain the words "see docs":
Setting perms of R and RW will no longer work; you have to say READERS and Setting perms of R and RW will no longer work; you have to say READERS and
WRITERS now. Suggested command: WRITERS now. Suggested command:
find `gitolite query-rc GL_REPO_BASE` -name gl-perms |
xargs perl -pi -e 's/\bR\b/READERS/;s/\bRW\b/WRITERS/'
## #rc-preset presetting the rc file ## #rc-preset presetting the rc file
Some rc settings in the older gitolite are such that you cannot directly run Some rc settings in the older gitolite are such that you cannot directly run