Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

added two "documentation map" pictures!

  • Loading branch information...
commit 3641d1b7ae96adba78d905553ef20d9c29c43446 1 parent 80f7742
@sitaramc authored
View
34 advanced.gv
@@ -0,0 +1,34 @@
+digraph G {
+
+ node [ shape = box ]
+ edge [ color = gray ]
+
+ gitolite [ label = "gitolite\nadvanced admnistration" style = filled fillcolor = lightblue ]
+ node [ fontcolor = darkgreen color = darkgreen ]
+ "server-side" -> "the RC file"
+ gitolite -> "server-side" -> "your own hooks"
+
+ node [ fontcolor = blue color = blue ]
+ gitolite -> "client-side"
+ "client-side" -> "conf file" -> "basic features"
+ "basic features" -> "access rules"
+ "basic features" -> options
+ "basic features" -> "git-config"
+ of1 [ label = "other features" ]
+ "conf file" -> of1
+ of1 -> "personal branches"
+ of1 -> delegation
+ of1 -> "'wild' repos\n(ad hoc, user-created, repos)"
+
+ node [ fontcolor = red color = red ]
+ of2 [ label = "other features" ]
+ gitolite -> of2
+ of2 -> "gitweb and\ngit-daemon"
+ of2 -> "mirroring"
+ cust [ label = "customising\ngitolite" ]
+ of2 -> cust
+ cust -> "types of non-core\nprograms"
+ ncs [ style=filled fillcolor=cyan label = "non-core programs\nshipped with gitolite" ]
+ cust -> ncs
+ cust -> "writing your own"
+}
View
43 basic.gv
@@ -0,0 +1,43 @@
+digraph G {
+
+ node [ shape = box ]
+ edge [ color = gray ]
+
+ emergency [ style = filled fillcolor = red label = "stuck?\nDON'T panic!" ]
+ node [ fontcolor = blue color = blue ]
+ introduction [ fontcolor = blue color = blue label = "introduction\nwhat, why, ..." ]
+ user [ label = "what your USERS\nneed to know"]
+ emergency -> introduction [ style = invis ]
+ introduction -> "doc index" [ style = invis ]
+ "doc index" -> user [ style = invis ]
+ emergency
+
+ node [ fontcolor = red color = red ]
+ minreq [ label = "minimum requirements" ]
+ try [ label = "trying it out\nsafely" ]
+ node [ fontcolor = darkgreen color = darkgreen ]
+ run [ label = "using gitolite" ]
+ quick [ label = "quick\ninstall/setup/clone" ]
+ detailed [ label = "(detailed)" ]
+ admin [ label = "basic administration" ]
+ v2 [ fontcolor = gray color = gray label = "migrating from v2" ]
+
+ gitolite [ label = "gitolite basics" style = filled fillcolor = lightblue ]
+ gitolite [ label = "gitolite\nbasic install and use" style = filled fillcolor = lightblue ]
+ gitolite -> minreq
+ gitolite -> try
+ gitolite -> v2
+ gitolite -> run
+
+ run -> quick
+ quick -> detailed [ label = "failed?" ]
+ detailed -> install
+ detailed -> setup
+ detailed -> clone
+
+ run -> admin
+
+ admin -> "add users"
+ admin -> "add repos"
+ admin -> "access control rules"
+}
View
2  cust.mkd
@@ -22,7 +22,7 @@ TOC
----
-## introduction
+## #ncintro introduction
There are 5 basic types of non-core programs.
View
9 emergencies.mkd
@@ -6,6 +6,15 @@
----
+## install/setup issues
+
+Most install/setup issues are caused by lack of ssh knowledge. Ssh is a
+complex beast, and -- unless you are using the [http][] mode -- can cause
+problems for people who are not familiar with its quirks.
+
+**Be prepared to spend some time reading the [ssh][] documentation that comes
+with gitolite**.
+
## #lost-key lost admin key/access
If you lost your gitolite **admin** key or access, here's what you do. We'll
View
38 html/advanced.html
@@ -0,0 +1,38 @@
+<html>
+<head>
+<title>gitolite -- advanced documentation map</title>
+</head>
+<body>
+
+<p>
+
+<strong>This map does NOT cover ALL the documentation available. The <a
+href="master-toc.html">master table of contents</a> is where you should expect
+to find everything.</strong>
+
+</p>
+
+<hr />
+
+<img src="images/advanced.png" usemap="#advanced">
+<map name="advanced">
+ <area shape="rect" href="wild.html" coords="652,397,880,447" />
+ <area shape="rect" href="dev-notes.html" coords="969,299,1115,347" />
+ <area shape="rect" href="non-core.html" coords="772,299,943,346" />
+ <area shape="rect" href="cust.html#tncp" coords="601,298,747,348" />
+ <area shape="rect" href="cust.html" coords="804,200,912,249" />
+ <area shape="rect" href="mirroring.html" coords="688,201,778,248" />
+ <area shape="rect" href="external.html" coords="557,199,662,250" />
+ <area shape="rect" href="special.html" coords="619,103,739,149" />
+ <area shape="rect" href="deleg.html" coords="530,398,625,445" />
+ <area shape="rect" href="special.html#pers" coords="353,398,504,446" />
+ <area shape="rect" href="git-config.html" coords="236,398,328,446" />
+ <area shape="rect" href="options.html" coords="137,398,210,446" />
+ <area shape="rect" href="rules.html" coords="4,397,111,445" />
+ <area shape="rect" href="admin.html#conf" coords="452,200,533,248" />
+ <area shape="rect" href="admin.html#adminrepo" coords="444,104,540,151" />
+ <area shape="rect" href="cust.html#hooks" coords="289,200,427,248" />
+ <area shape="rect" href="rc.html" coords="162,200,263,248" />
+ <area shape="rect" href="admin.html#server" coords="307,102,408,149" />
+</map></body>
+</html>
View
35 html/basic.html
@@ -0,0 +1,35 @@
+<html>
+<head>
+<title>gitolite -- basic documentation map</title>
+</head>
+<body>
+
+<p>
+
+<strong>This map does NOT cover ALL the documentation available. The <a
+href="master-toc.html">master table of contents</a> is where you should expect
+to find everything.</strong>
+
+</p>
+
+<hr />
+
+<img src="images/basic.png" usemap="#basic">
+<map name="basic">
+ <area shape="rect" href="admin.html#adminrepo" coords="790,330,951,375" />
+ <area shape="rect" href="repos.html" coords="675,330,764,375" />
+ <area shape="rect" href="users.html" coords="559,328,648,376" />
+ <area shape="rect" href="clone.html" coords="550,429,620,476" />
+ <area shape="rect" href="setup.html" coords="453,430,523,475" />
+ <area shape="rect" href="install.html" coords="356,429,428,476" />
+ <area shape="rect" href="qi.html" coords="425,207,576,258" />
+ <area shape="rect" href="install.html#migr" coords="661,106,818,154" />
+ <area shape="rect" href="testing.html#trying" coords="388,106,495,156" />
+ <area shape="rect" href="install.html#req" coords="168,108,363,156" />
+ <area shape="rect" href="user.html" coords="6,329,158,378" />
+ <area shape="rect" href="master-toc.html" coords="35,209,126,255" />
+ <area shape="rect" href="index.html" coords="22,107,143,156" />
+ <area shape="rect" href="index.html" coords="400,6,568,54" />
+ <area shape="rect" href="emergencies.html" coords="19,5,145,56" />
+</map></body>
+</html>
View
BIN  images/advanced.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  images/basic.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
6 index.mkd
@@ -6,6 +6,12 @@ fine-grained access control and many more powerful features.
Here's more on [what][] it is, [how][] it works, [why][] you might need it,
and [who][] else is using it.
+**If you think there's too much documentation, try this different way of
+accessing the [basic][] stuff and the [advanced][] stuff.**
+
+[basic]: basic.html
+[advanced]: advanced.html
+
<font color="gray">
## #g2 (for older gitolite (v1.x and v2.x) users)
View
10 install.mkd
@@ -42,8 +42,9 @@ Notes:
### your skills
* If you're installing gitolite, you're a "system admin", like it or not.
- Ssh is therefore a necessary skill. Please take the time to learn at
- least enough to get passwordless access working.
+ Since most people use the ssh mode, **[ssh][]** is therefore a necessary
+ skill. Please take the time to learn at least enough to get passwordless
+ access working.
* You also need to be somewhat familiar with git itself. You cannot
administer a whole bunch of git repositories if you don't know the basics
@@ -56,8 +57,9 @@ Notes:
### server
- * Any Unix system with a posix compatible "sh".
- * Git version 1.6.6 or later.
+ * Any Unix system with a posix compatible "sh" and a **sane** file system.
+ * Git version 1.6.6 or later. (Git 1.7.8 or later if you want to run the
+ test suite).
* Perl 5.8.8 or later.
* Openssh (almost any version). Optional if you're using [smart
http][http].
View
2  master-toc.mkd
@@ -127,7 +127,7 @@ since there are so many of them**.
## customising gitolite
* [customisation][cust] overview
- * introduction
+ * [introduction][ncintro]
* [where][ncloc] do you put custom code?
* ([link][pushcode]: updating code via the admin repo)
* [types][nctypes] of non-core programs
View
74 testing.mkd
@@ -1,17 +1,52 @@
-# testing gitolite
+# trying out gitolite safely
-The test suite should run fine on most recent Linuxes and Unixes. Although
-gitolite itself should work fine with any git after 1.6.6 or so, the test
-suite requires git 1.7.8 or later.
-
-Here's how to *run* the tests.
+## #trying trying out gitolite
-<font color="red">**WARNING: they will clobber lots of things in your `$HOME`,
+<font color="red">**WARNING: this will clobber lots of things in your `$HOME`,
so be sure to use a throwaway userid**.</font>
+It's easy to take gitolite for a trial run, in ssh mode, and play with all of
+its features (except mirroring).
+
+Create a **throw-away userid**, log in to it, then run these commands:
+
git clone git://github.com/sitaramc/gitolite
cd gitolite
- prove
+ prove t/ssh*
+
+You will get an error that forces you to read `t/README` and set an env var
+before the test can proceed. This is intentional; I've had people who don't
+pay attention to the "data loss" warning, and then complain that it was not
+prominent enough. Forcing them to read a much smaller document appears to
+focus their attention better!
+
+If it doesn't work, read the testing section below to see if your system
+satisfies the conditions required for doing this.
+
+If it works, you get a gitolite installation with 7 gitolite users ("admin",
+and "u1" through "u6").
+
+Don't forget that the client and the server are all on the same user on the
+same machine; we're *simulating* 7 gitolite users using ssh keys! (How?
+Maybe `~/.ssh/config` will give you a hint).
+
+URLs look like `user:repo`, so for example you can clone the admin repo by
+`git clone admin:gitolite-admin`. Remote commands look like `ssh u1 info`.
+
+So start by cloning the admin repo, and try out whatever you want!
+
+## testing gitolite
+
+<font color="red">**WARNING: this will clobber lots of things in your `$HOME`,
+so be sure to use a throwaway userid**.</font>
+
+Trying out gitolite safely is really a subset of running the test suite. If
+you want to run the full test suite, just do as above, except instead of
+running `prove t/ssh*` you just run `prove`.
+
+The test suite should run fine on most recent Linuxes and Unixes. Although
+gitolite itself should work fine with any git after 1.6.6 or so, the test
+suite requires git 1.7.8 or later.
Make sure:
@@ -20,7 +55,7 @@ Make sure:
Gitolite's test suite is mostly written using [tsh][] -- the "testing shell".
Take a look at some of the scripts and you will see what it looks like. It
-has a few quirks and nuances; if you really care, email me.
+has a few quirks and nuances, but it's fine for what I need here.
[tsh]: http://github.com/sitaramc/tsh
@@ -31,24 +66,3 @@ would otherwise take.
If you think that defeats the purpose of the testing, you haven't read
[this][auth] yet.
-
-## #trying trying out gitolite
-
-It's easy to take gitolite for a trial run, in ssh mode, and play with all of
-its features (except mirroring).
-
-Create a **throw-away userid**, log in to it, then do what the "testing
-gitolite" section above says, except instead of running `prove`, you run
-`prove t/ssh*`.
-
-When this is done, you get a gitolite installation with 7 gitolite users
-("admin", and "u1" through "u6").
-
-Don't forget that the client and the server are all on the same user on the
-same machine; we're *simulating* 7 gitolite users using ssh keys! (How?
-Maybe `~/.ssh/config` will give you a hint).
-
-URLs look like `user:repo`, so for example you can clone the admin repo by
-`git clone admin:gitolite-admin`. Remote commands look like `ssh u1 info`.
-
-So start by cloning the admin repo, and try out whatever you want!
Please sign in to comment.
Something went wrong with that request. Please try again.