From a502d96a860456ec5e8c96761db70f7cabb74751 Mon Sep 17 00:00:00 2001
From: Paul Martin <paul@paulsputer.com>
Date: Sat, 30 Apr 2016 04:19:14 -0400
Subject: [PATCH] Merge pull request #1073 from gitblit/1062-DocEditorUpdates

---
 src/site/faq.mkd |   63 ++++++++++---------------------
 1 files changed, 21 insertions(+), 42 deletions(-)

diff --git a/src/site/faq.mkd b/src/site/faq.mkd
index 84a0a81..160808d 100644
--- a/src/site/faq.mkd
+++ b/src/site/faq.mkd
@@ -1,5 +1,13 @@
 ## Troubleshooting
 
+### push failed for branch (n/a (unpacker error))
+
+This is a bug in JGit (issue-408).  TLDR: Newer git clients are optimized to send less data on the wire.  JGit expects complete data to be sent, but there are scenarios where native git can optimize-out sending objects.  By default, JGit requires everything sent be complete and referenceable.
+
+If you experience this, the workaround is to temporarily disable the reachable check for the receive pack, push, and then re-enable the setting.
+
+    git.checkReferencedObjectsAreReachable = false
+
 ### Eclipse/Egit/JGit complains that it "can't open upload pack"?
 There are a few ways this can occur:
 
@@ -9,10 +17,7 @@
     2. Click the *New Entry* button
     3. <pre>Key = <em>http.sslVerify</em>
 Value = <em>false</em></pre>
-3. Gitblit GO's default self-signed certificate is bound to *localhost* and you are trying to clone/push between machines.
-    1. Review the contents of `makekeystore.cmd`
-    2. Set *your hostname* in the *HOSTNAME* variable.
-    3. Execute the script.<br/>This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*. 
+3. Gitblit GO's default self-signed certificate is bound to *localhost* and you are trying to clone/push from a client based on an old version of JGit with a known flaw.
 4. The repository is clone-restricted and you don't have access.
 5. The repository is clone-restricted and your password changed.
 6. A regression in Gitblit.  :(
@@ -21,7 +26,7 @@
 
 This is a long-standing, known bug in the native Git for Windows implementation.
 
-https://groups.google.com/d/topic/msysgit/at8D7J-h7mw/discussion
+Please see [this thread](https://groups.google.com/d/topic/msysgit/at8D7J-h7mw/discussion) for details.
 
 ### Why can't I access Gitblit GO from another machine?
 1. Please check *server.httpBindInterface* and *server.httpsBindInterface* in `gitblit.properties`, you may be only be serving on *localhost*.
@@ -32,16 +37,9 @@
 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). 
 
-### Gitblit GO does not list my repositories?!
+### Gitblit does not list my repositories?!
 1. Confirm that the value *git.repositoriesFolder* in `gitblit.properties` actually points to your repositories folder.
-2. Confirm that the Gitblit GO process has full read-write-execute permissions to your *git.repositoriesFolder*. 
-
-### Gitblit WAR does not list my repositories?!
-1. Confirm that the &lt;context-param&gt; *git.repositoriesFolder* value in your `web.xml` file actually points to your repositories folder.
-2. Confirm that the servlet container process has full read-write-execute permissions to your *git.repositoriesFolder*.
-
-### Gitblit WAR will not authenticate any users?!
-Confirm that the &lt;context-param&gt; *realm.userService* value in your `web.xml` file actually points to a `users.conf` or `users.properties` file.
+2. Confirm that the Gitblit process has full read-write-execute permissions to your *git.repositoriesFolder*. 
 
 ### Gitblit won't open my grouped repository (/group/myrepo.git) or browse my log/branch/tag/ref?!
 This is likely an url encoding/decoding problem with forward slashes:
@@ -98,43 +96,30 @@
 
 Gitblit is not meant to be a social coding resource like [Github](http://github.com) or [Bitbucket](http://bitbucket.com) with 100s or 1000s of users.  Gitblit is designed to fulfill the same function as your centralized Subversion or CVS server.
 
-### Why does Gitblit exist when there is Git and Gitweb?
-As a Java developer I prefer that as much of my tooling as possible is Java.<br/>
-Originally, I was going to use [Mercurial](http://mercurial.selenic.com) but...
-
-- MercurialEclipse [shells to Python, writes to System.out, and captures System.in](http://mercurial.808500.n3.nabble.com/Hg4J-Mercurial-pure-Java-library-tp2693090p2694555.html)<br/>
-Parsing command-line output is fragile and suboptimal.<br/>Unfortunately this is necessary because Mercurial is an application, not a library.
-- Mercurial HTTP/HTTPS needs to run as CGI through Apache/IIS/etc, as mod_python through Apache, or served with a built-in http server.<br/>
-This requires setup and maintenance of multiple, mixed 3rd party components.
-
-Gitblit eliminates all that complication with its 100% Java stack and simple single configuration file.
-
-Additionally, Git and Gitweb do not offer repository creation or user management.
-
 ### Do I need real Git?
-No (mostly).  Gitblit is based on [JGit][jgit] which is a pure Java implementation of the [Git version control system][git].<br/>
-Everything you need for Gitblit (except Java) is either bundled in the distribution file or automatically downloaded on execution.
+No (mostly).  Gitblit is based on [JGit][jgit] which is a pure Java implementation of the [Git version control system][git].
+Everything you need for Gitblit (except Java) is bundled in the distribution file.
 
 #### mostly
-JGit does not fully support the git-gc featureset (garbage collection) so you may want native Git to periodically run git-gc until [JGit][jgit] fully supports this feature.
+Gitblit has experimental support for Garbage Collection using JGit.  I have not used it enough to feel comfortable removing the EXPERIMENTAL label.  It may work really well, or it may not.  One thing you might consider having native git for is periodic garbage collection - when Gitblit is offline.
 
 ### Can I run Gitblit in conjunction with my existing Git tooling?
 Yes.
 
 ### 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.
+Gitblit will run just fine with a JRE.
 
 ### 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.conf`, `users.properties`, or whatever filename is configured in `gitblit.properties`.
+No.  Gitblit stores its repository configuration information within the `.git/config` file and its user information in `users.conf` or whatever filename is configured in `gitblit.properties`.
 
-### Can I manually edit users.conf, users.properties, gitblit.properties, or .git/config?
+### Can I manually edit users.conf, 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 *User Roles* section of the [setup](/setup.html) page for details.
 
 ### Can I restrict access to branches or paths within a repository?
-No, not out-of-the-box.  Access restrictions apply to the repository as a whole.
+No, not yet.  Access restrictions apply to the repository as a whole.
 
 Gitblit's simple authentication and authorization mechanism can be used to facilitate one or more of the [workflows outlined here](http://progit.org/book/ch5-1.html).
 
@@ -145,17 +130,11 @@
 ### Can I authenticate users against XYZ?
 Yes.  The user service is pluggable.  You may write your own complete user service by implementing the *com.gitblit.IUserService* interface.  Or you may subclass *com.gitblit.GitblitUserService* and override just the authentication. Set the fully qualified classname as the *realm.userService* property.
 
-### 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 (arguably not more complicated than managing users).  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).
-
 ### What types of Search does Gitblit support?
 
 As of 0.9.0, Gitblit supports Lucene-based searching.
 
-If Lucene indexing is disabled, Gitblit falls back to brute-force commit-traversal search.  Commit-traversal search supports case-insensitive searching of *commit message* (default), *author*, and *committer*.<br/>
+If Lucene indexing is disabled, Gitblit falls back to brute-force commit-traversal search.  Commit-traversal search supports case-insensitive searching of *commit message* (default), *author*, and *committer*.
 
 To search by *author* or *committer* use the following syntax in the search box:
 
@@ -176,4 +155,4 @@
 [jgit]: http://eclipse.org/jgit "Eclipse JGit Site"
 [git]: http://git-scm.com "Official Git Site"
 [mina]: http://mina.apache.org "Apache Mina"
-[bouncycastle]: http://bouncycastle.org "The Legion of the Bouncy Castle"
\ No newline at end of file
+[bouncycastle]: http://bouncycastle.org "The Legion of the Bouncy Castle"

--
Gitblit v1.9.1