From 867b34f32c987ccba95c7bd1d606724f4440dbaa Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Sun, 8 May 2011 12:56:26 +0530 Subject: [PATCH] (doc) ADCs now have an overview doc, plus... - repo-deletion is now a proper doc - other doc enhancements and clarifications --- README.mkd | 10 ++- contrib/adc/README.mkd | 63 +++++++++++++++++++ ...repo-deletion.README => repo-deletion.mkd} | 9 ++- doc/1-INSTALL.mkd | 38 ++++++----- 4 files changed, 97 insertions(+), 23 deletions(-) create mode 100644 contrib/adc/README.mkd rename contrib/adc/{repo-deletion.README => repo-deletion.mkd} (84%) diff --git a/README.mkd b/README.mkd index b3d27d3..b60683c 100644 --- a/README.mkd +++ b/README.mkd @@ -2,8 +2,13 @@ -***IMPORTANT NOTE: v2.0rc1 is out; all development will be on that now. -Please see new doc/developer-notes.mkd*** +***IMPORTANT NOTE: There is a [master table of contents of all gitolite +documentation][docs] that can help if you're looking for stuff. Just click +the link and use your browser's search function (Ctrl-F, usually) to look for +likely sounding words. All documents are listed, as well as links to section +headers in some of the longer documents*** + +[docs]: http://sitaramc.github.com/gitolite ---- @@ -196,7 +201,6 @@ Gitolite is released under GPL v2. See COPYING for details. [install]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html [admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html [migr]: http://sitaramc.github.com/gitolite/doc/migrate.html -[docs]: http://sitaramc.github.com/gitolite [doc9gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html [doc6sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html [who]: http://sitaramc.github.com/gitolite/doc/who-uses-it.html diff --git a/contrib/adc/README.mkd b/contrib/adc/README.mkd new file mode 100644 index 0000000..6467957 --- /dev/null +++ b/contrib/adc/README.mkd @@ -0,0 +1,63 @@ +# brief descriptions of the shipped ADCs (admin-defined commands) + +(...with pointers to further information where needed) + +---- + +**able**: enable/disable push access temporarily (such as for taking backups +or other admin chores); details [here][able]. + +[able]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_enable_disable_push_access_temporarily + +**delete-branch**: allow someone to delete a branch that they themselves +created. (i.e., when the user had RWC, but not RWCD, permissions). Details on +this ADC are [here][dbsha]; details on RWC/RWD/RWCD etc are [here][rwcd]. + +[dbsha]: https://github.com/sitaramc/gitolite/commit/89b68bf5ca99508caaa768c60ce910d7e0a29ccf +[rwcd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_creating_and_deleting_branches + +**fork**: Think of it as a server-side clone; details [here][fork]. + +[fork]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_fork + +**get-rights-and-owner.in-perl**: Most of the ADCs are in shell, so this is a +sample of how to write an ADC in perl. + +**gl-reflog**: show a fake "reflog" from the server, and allow recovery from +deleted branches and bad force pushes; details in source. + +**help**: not all shipped ADCs may be enabled by the site admin. Conversely +the admin may create and install his own ADCs that dont ship with gitolite +itself. This ADC displays site-local help, if the site admin enabled it. + +**hub**: allow "pull requests" a la github; details [here][hub]. + +[hub]: http://sitaramc.github.com/gitolite/contrib/adc/hub.html + +**rm**, **lock**, and **unlock**:
+**trash**, **list-trash**, and **restore**: + +> two families of repo deletion commands; details [here][rddoc] + +[rddoc]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html + +**restrict-admin**: sample program to show how you can allow the admin to run +pre-specified shell commands (without actually having full shell access). +Details [here][ra]. + +[ra]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_bonus_restricted_admin + +**sudo**: allow admin to run ADCs on behalf of a user. Useful in support +situations I guess. Details in source. + +Note: the Unix "sudo" and "su" programs are most often used to acquire +*higher* privileges, although they're actually designed to go the other way +also. In gitolite we do not do the former, only the latter (i.e., a normal +gitolite user cannot do admin-stuff using this ADC). + +**su-expand**, **su-getperms**, **su-setperms**: as above, but for the +internal commands 'expand', 'getperms', and 'setperms'. (These commands are +not ADCs so you cannot simply use the 'sudo' ADC described above). + +**who-pushed**: find the last person to push a given commit; details in +source. diff --git a/contrib/adc/repo-deletion.README b/contrib/adc/repo-deletion.mkd similarity index 84% rename from contrib/adc/repo-deletion.README rename to contrib/adc/repo-deletion.mkd index a2a8609..c46e151 100644 --- a/contrib/adc/repo-deletion.README +++ b/contrib/adc/repo-deletion.mkd @@ -1,6 +1,8 @@ # deleting repos safely -(see http://groups.google.com/group/gitolite/browse_thread/thread/fb9cf5a464b6dfee ) +(see [this thread][thr] on the gitolite mailing list) + +[thr]: http://groups.google.com/group/gitolite/browse_thread/thread/fb9cf5a464b6dfee By default, the old 'rmrepo' ADC (admin-defined command) just went and deleted the repo -- no questions asked! Sometimes, that could be a disaster -- you @@ -13,12 +15,13 @@ either, both, or neither family of commands. Local settings for these ADCs can be found in the common settings file "adc.common-functions". -1. 'rm' will remove the repo. If USE_LOCK_UNLOCK is set, rm will refuse to +1. 'rm' will remove the repo. If `USE_LOCK_UNLOCK` is set, rm will refuse to remove a locked repo. All repos are locked by default, and you have to explicitly 'unlock' a repo to remove it. You can also 'lock' it again instead of removing it of course. - There's also ARE_YOU_SURE, for situations where a simple warning suffices. + There's also `ARE_YOU_SURE`, for situations where a simple warning + suffices. You can also use both these flags if you wish. diff --git a/doc/1-INSTALL.mkd b/doc/1-INSTALL.mkd index 9885013..74a0ad7 100644 --- a/doc/1-INSTALL.mkd +++ b/doc/1-INSTALL.mkd @@ -8,11 +8,11 @@ In this document: * client/workstation * server * technical skills + * naming conventions used * getting the gitolite software * getting a tar file from a clone * installation and setup * install methods and deciding which one to use - * conventions used * (package method) directly on the server, using RPM/DEB * (root method) directly on the server, manually, with root access * (non-root method) directly on the server, manually, without root access @@ -131,6 +131,22 @@ don't know ssh it'll be a nightmare to support you. * regular expressions are a big part of gitolite in many places but familiarity is not necessary to do basic access control. + + +#### naming conventions used + +Throughout the documentation, we use "YourName" as the admin user, and his +workstation is called "client". The hosting user is "git", and the server is +called "server". **Please substitute your values as needed**. + +**If you're using DEB or RPM**, the installer creates a user called +"gitolite", so substitute that for "git" anywhere in the docs where the +"hosting user" is mentioned as "git". + +Also, we often say "the rc file". This means `~/.gitolite.rc` on the server. +And when we say the "access control rules", or "conf file", or "config file", +we mean `conf/gitolite.conf` on your gitolite-admin clone. + ### getting the gitolite software @@ -184,22 +200,6 @@ Gitolite has 4 install methods: Here's how you install using these 3 methods. Future upgrades are equally easy -- the steps required for upgrading are marked "(U)". - - -#### conventions used - -Throughout the documentation, we use "YourName" as the admin user, and his -workstation is called "client". The hosting user is "git", and the server is -called "server". **Please substitute your values as needed**. - -**If you're using DEB or RPM**, the installer creates a user called -"gitolite", so substitute that for "git" anywhere in the docs where the -"hosting user" is mentioned as "git". - -Also, we often say "the rc file". This means `~/.gitolite.rc` on the server. -And when we say the "access control rules", or "conf file", or "config file", -we mean `conf/gitolite.conf` on your gitolite-admin clone. - #### (package method) directly on the server, using RPM/DEB @@ -253,6 +253,9 @@ possible, you should (a) know the password in case you screw up the keys AND (b) know how to force ssh to ask for a password if required, AND (c) know how to handle multiple keys in ssh.** +***NOTE: if this is still confusing, try the [tutorial][tut]. That was +written for this specific method of install.*** + * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server. Put it in `/tmp/YourName.pub`. @@ -429,3 +432,4 @@ uninstalling gitolite is described in great detail in [transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html [mgs]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_special_cases_multiple_gitolite_servers [gash]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html +[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial