From 1f9daef870a8c7a984955166a542628d69012ed5 Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Fri, 27 May 2011 23:37:24 -0400
Subject: Codepro analyze dependencies. Documentation.

---
 docs/00_index.mkd      |  11 +++++++----
 docs/00_setup.mkd      |  23 +++++++++++++++++++++--
 docs/01_eclipse.mkd    |  18 ------------------
 docs/01_faq.mkd        |  43 ++++++++++++++++++++++++++++++++++---------
 docs/02_properties.mkd |   4 ++++
 docs/page_header.html  |   6 +++++-
 docs/sslverify.png     | Bin 48728 -> 0 bytes
 docs/sslverify2.png    | Bin 21758 -> 0 bytes
 8 files changed, 71 insertions(+), 34 deletions(-)
 delete mode 100644 docs/01_eclipse.mkd
 create mode 100644 docs/02_properties.mkd
 delete mode 100644 docs/sslverify.png
 delete mode 100644 docs/sslverify2.png

(limited to 'docs')

diff --git a/docs/00_index.mkd b/docs/00_index.mkd
index e21a158b..9ad1c4e8 100644
--- a/docs/00_index.mkd
+++ b/docs/00_index.mkd
@@ -107,10 +107,10 @@ The following dependencies are automatically downloaded from the Apache Maven re
 - [JSch - Java Secure Channel](http://www.jcraft.com/jsch) (BSD)
 - [JUnit](http://junit.org) (Common Public License)
 
-## Building
+## Building from Source
 [Eclipse](http://eclipse.org) is recommended for development as the project settings are preconfigured.
 
-Additionally, [Google CodePro AnalytiX](http://code.google.com/javadevtools), [eclipse-cs](http://eclipse-cs.sourceforge.net), and [FindBugs](http://findbugs.sourceforge.net) are recommended development tools.
+Additionally, [Google CodePro AnalytiX](http://code.google.com/javadevtools), [eclipse-cs](http://eclipse-cs.sourceforge.net), [FindBugs](http://findbugs.sourceforge.net), and [EclEmma](http://www.eclemma.org) are recommended development tools.
 
 1. Clone the git repository from [Github][gitbltsrc].
 2. Import the gitblit project into your Eclipse workspace.<br/>
@@ -118,8 +118,11 @@ Additionally, [Google CodePro AnalytiX](http://code.google.com/javadevtools), [e
 3. Using Ant, execute the `build.xml` script in the project root.<br/>
 *This will download all necessary build dependencies and will also generate the Keys class for accessing settings.*
 4. Select your gitblit project root and **Refresh** the project, this should correct all build problems.
-5. Review the settings in `gitblit.properties` in your project root.<br/>
-Make sure you set an appropriate value for *git.repositoriesFolder*. 
+5. Using JUnit, execute the `com.gitblit.tests.GitBlitSuite` test suite.<br/>
+*This will clone some repositories from the web and run through the unit tests.*
+5. Review the settings in `gitblit.properties` in your project root.
+    - By default, the *git.repositoriesFolder* points to the repositories cloned by the test suite.<br/>
+    - If running on Linux you may have to change the served port(s) to > 1024 unless you are developing as the root user. 
 6. Execute the *com.gitblit.Launcher* class to start Gitblit.
 
 [jgit]: http://eclipse.org/jgit "Eclipse JGit Site"
diff --git a/docs/00_setup.mkd b/docs/00_setup.mkd
index 447f1515..99fd05fc 100644
--- a/docs/00_setup.mkd
+++ b/docs/00_setup.mkd
@@ -1,4 +1,4 @@
-## Setup and Configuration
+## Server Setup and Configuration
 
 1. Download and unzip [Gitblit %VERSION%](http://gitblit.com/%DISTRIBUTION%).<br/>
 *Its best to eliminate spaces in the path name as that can cause troubleshooting headaches.* 
@@ -74,4 +74,23 @@ Set the *JVM* variable in the script to the location of your Java Virtual Machin
     
 **Example**
 
-    java -jar gitblit.jar --realmFile c:\myrealm.txt --storePassword something
\ No newline at end of file
+    java -jar gitblit.jar --realmFile c:\myrealm.txt --storePassword something
+    
+## Client Setup and Configuration
+### Https with Self-Signed Certificates
+You must tell Git not to verify the self-signed certificate in order to perform any remote Git operations.
+
+- Eclipse/EGit
+    1. Window->Preferences->Team->Git->Configuration
+    2. Click the *New Entry* button
+    3. <pre>Key = *http.sslVerify*       
+       Value = *false*</pre>
+- Command-line Git ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
+    <pre>git-config --global --bool --add http.sslVerify false</pre>
+
+### Cloning an Access Restricted Repository 
+- Eclipse/Egit<br/>Nothing special to configure, EGit figures out everything.
+    <pre>https://yourserver/git/your/repository</pre>
+- Command-line Git<br/>*My testing indicates that your username must be embedded in the url.  YMMV.*
+    <pre>https://username@yourserver/git/your/repository</pre>
+           
\ No newline at end of file
diff --git a/docs/01_eclipse.mkd b/docs/01_eclipse.mkd
deleted file mode 100644
index e768b73a..00000000
--- a/docs/01_eclipse.mkd
+++ /dev/null
@@ -1,18 +0,0 @@
-## Eclipse Tips
-
-### Do Not Verify Self-Signed Certificates
-If you are using a self-signed certificate, like the one that is automatically generated by Gitblit, you have to tell Eclipse/EGit to ignore certificate verification errors.
-
-![sslverify](sslverify.png "http.sslVerify setting")
-
-![sslverify2](sslverify2.png "Adding http.sslVerify setting")    
-
-### Pushing a New Project to a New Gitblit Repository
-1. Project Root->Team->Share->Git
-Create a Git repository inside the project
-
-### Pushing a Git-Controlled Project to another Gitblit Repository
-1. Project Root->Team->Remote->Push
-2. Enter the URL information of the repository
-3. In the Refspec dialog click the buttons named  "All all branches spec" and "All all tags spec"
-
diff --git a/docs/01_faq.mkd b/docs/01_faq.mkd
index 86aa9ad2..5068e79a 100644
--- a/docs/01_faq.mkd
+++ b/docs/01_faq.mkd
@@ -1,10 +1,31 @@
-## Frequently Asked Questions
+## Troubleshooting
+
+### Eclipse/Egit/Git complains that it "can't open upload pack"?
+There are a few ways this can occur:
+
+1. You are using https with a self-signed certificate and you **did not** configure *http.sslVerify=false*
+    1. Window->Preferences->Team->Git->Configuration
+    2. Click the *New Entry* button
+    3. <pre>Key = *http.sslVerify*       
+       Value = *false*</pre>
+2. The repository is clone-restricted and you don't have access.
+3. The repository is clone-restricted and your password changed.
+4. A regression in Gitblit.  :(
+
+### Why can't I access Gitblit from another machine?
+Please check *server.httpBindInterface* and *server.httpsBindInterface* in `gitblit.properties`.
+
+### How do I run Gitblit on port 80 or 443 in Linux?
+Linux requires root permissions to serve on ports < 1024.<br/>
+Run the server as *root* (security concern) or change the ports you are serving to 8080 (http) and/or 8443 (https). 
+
+## General Interest Questions
 
 ### Gitblit?  What kind of name is that?
-Its a phonetic play on [bitblt][bitblt] which is an image processing operation meaning *bit-block transfer*.
+It's a phonetic play on [bitblt][bitblt] which is an image processing operation meaning *bit-block transfer*.
 
 ### Why use Gitblit?
-Its small.  Its portable.  Its easy to manage.
+It's a small tool that allows you to easily manage shared repositories and doesn't require alot of setup or git kung-foo.
 
 ### Do I need real Git?
 No.  Gitblit is based on [JGit][jgit] which is a pure Java implementation of the [Git version control system][git].<br/>
@@ -13,11 +34,16 @@ Everything you need for Gitblit is either in the zip distribution file or automa
 ### Do I need a JDK or can I use a JRE?
 Gitblit will run just fine with a JRE.  Gitblit can optionally use `keytool` from the JDK to generate self-signed certificates, but normally Gitblit uses [BouncyCastle][bouncycastle] for that need.
 
+### I want to deploy Gitblit into my own servlet container.  Where is the WAR?
+At this time there is no WAR build available.
+
 ### Does Gitblit use a database to store its data?
 No.  Gitblit stores its repository configuration information within the `.git/config` file and its user information in `users.properties` or whatever filename is configured in `gitblit.properties`.
 
-### I want to deploy Gitblit into my own servlet container.  Where is the WAR?
-At this time there is no WAR build available.
+### Can I manually edit users.properties, gitblit.properties, or .git/config?
+Yes.  You can manually manipulate all of them and (most) changes will be immediately available to Gitblit.<br/>Exceptions to this are noted in `gitblit.properties`.
+
+*NOTE:* Care must be taken to preserve the relationship between user roles and repository names.<br/>Please see the [setup](/setup.html) page for details.
 
 ### Can I restrict access to paths within a repository?
 No.  Access restrictions apply to the repository as a whole.
@@ -26,7 +52,7 @@ Gitblit's simple authentication and authorization mechanism can be used to facil
 
 ### Why doesn't Gitblit support SSH?
 Gitblit could integrate [Apache Mina][mina] to provide SSH access.  However, doing so violates Gitblit's first design principle: [KISS](http://en.wikipedia.org/wiki/KISS_principle).<br/>
-SSH support requires creating, exchanging, and managing SSH keys.  While this is possible, JGit's SmartHTTP implementation is a simpler and cleaner transport mechanism.
+SSH support requires creating, exchanging, and managing SSH keys.  While this is possible, JGit's SmartHTTP implementation is a simpler and universal transport mechanism.
 
 You might consider running [Gerrit](http://gerrit.googlecode.org) which does integrate [Apache Mina][mina] and supports SSH or you might consider serving [Git][git] on Linux which would offer real SSH support and also allow use of [many other compelling Git solutions](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools).
 
@@ -40,9 +66,8 @@ To search by *author* or *committer* use the following syntax in the search box:
     
 Alternatively, you could enable the search type dropdown list in your `gitblit.properties` file.
 
-### How do I run Gitblit on port 80 or 443 in Linux?
-Linux requires root permissions to serve on ports < 1024.<br/>
-Run the server as *root* (security concern) or change the ports you are serving to 8080 (http) and/or 8443 (https). 
+### I see a disabled "blame" link. How do I enable it? 
+Currently blame is not implemented.  Those links are placeholders to remind me where Gitweb offers blame.
 
 [bitblt]: http://en.wikipedia.org/wiki/Bit_blit "Wikipedia Bitblt"
 [jgit]: http://eclipse.org/jgit "Eclipse JGit Site"
diff --git a/docs/02_properties.mkd b/docs/02_properties.mkd
new file mode 100644
index 00000000..3a1dec17
--- /dev/null
+++ b/docs/02_properties.mkd
@@ -0,0 +1,4 @@
+## gitblit.properties
+<pre class='prettyprint'>
+%PROPERTIES%
+</pre>
\ No newline at end of file
diff --git a/docs/page_header.html b/docs/page_header.html
index fd40c5a2..4a2128e0 100644
--- a/docs/page_header.html
+++ b/docs/page_header.html
@@ -8,6 +8,7 @@
 		<meta name="ROBOTS" content="INDEX, NOFOLLOW">
 		<meta http-equiv="imagetoolbar" content="no" />
 		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+		<meta name="keywords" content="java git server" />
 		
 		<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
 		<script>
@@ -23,8 +24,11 @@
 				list-style: none;
 			'}'
 		</style>
+		
+		<script type="text/javascript" src="prettify/prettify.js"></script>
+		<link href="prettify/prettify.css" type="text/css" rel="stylesheet" />		
 	</head>
-	<body>
+	<body onload="prettyPrint()">
 		<div class="page_header">
 			<a title="gitblit homepage" href="http://gitblit.com/">
 				<img src="./gitblt_25.png" width="79" height="25" alt="gitblit" class="logo"/>
diff --git a/docs/sslverify.png b/docs/sslverify.png
deleted file mode 100644
index e987b9f0..00000000
Binary files a/docs/sslverify.png and /dev/null differ
diff --git a/docs/sslverify2.png b/docs/sslverify2.png
deleted file mode 100644
index 94db9776..00000000
Binary files a/docs/sslverify2.png and /dev/null differ
-- 
cgit v1.2.3