James Moger
2014-02-26 87066a663797d6f17a16b269ed19199b8b50fe84
commit | author | age
1f9dae 1 ## Troubleshooting
JM 2
d39680 3 ### Eclipse/Egit/JGit complains that it "can't open upload pack"?
1f9dae 4 There are a few ways this can occur:
JM 5
2fe1e2 6 1. Are you running Java 7?<br />Java 7 introduced SNI support for SSL connections and it is enabled by default.<br />[Java 7 Security Enhancements](http://docs.oracle.com/javase/7/docs/technotes/guides/security/enhancements-7.html)<br />To disable SNI alerts, add this line to your eclipse.ini file and restart Eclipse.<br /><pre>-Djsse.enableSNIExtension=false</pre>
JM 7 2. You are using https with a self-signed certificate and you **did not** configure *http.sslVerify=false*
1f9dae 8     1. Window->Preferences->Team->Git->Configuration
JM 9     2. Click the *New Entry* button
3b5289 10     3. <pre>Key = <em>http.sslVerify</em>
JM 11 Value = <em>false</em></pre>
87066a 12 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.
2fe1e2 13 4. The repository is clone-restricted and you don't have access.
JM 14 5. The repository is clone-restricted and your password changed.
15 6. A regression in Gitblit.  :(
1f9dae 16
99c974 17 ### I can not push using git:// protocol on Windows using native Git
JM 18
19 This is a long-standing, known bug in the native Git for Windows implementation.
20
cc0477 21 Please see [this thread](https://groups.google.com/d/topic/msysgit/at8D7J-h7mw/discussion) for details.
99c974 22
85c2e6 23 ### Why can't I access Gitblit GO from another machine?
d39680 24 1. Please check *server.httpBindInterface* and *server.httpsBindInterface* in `gitblit.properties`, you may be only be serving on *localhost*.
JM 25 2. Please see the above answer about "**can't open upload pack**".
26 3. Ensure that any firewall you may have running on the Gitblit server either has an exception for your specified ports or for the running process.
85c2e6 27
JM 28 ### How do I run Gitblit GO on port 80 or 443 in Linux?
1f9dae 29 Linux requires root permissions to serve on ports < 1024.<br/>
JM 30 Run the server as *root* (security concern) or change the ports you are serving to 8080 (http) and/or 8443 (https). 
85c2e6 31
87066a 32 ### Gitblit does not list my repositories?!
d39680 33 1. Confirm that the value *git.repositoriesFolder* in `gitblit.properties` actually points to your repositories folder.
87066a 34 2. Confirm that the Gitblit process has full read-write-execute permissions to your *git.repositoriesFolder*. 
1f9dae 35
70b492 36 ### Gitblit won't open my grouped repository (/group/myrepo.git) or browse my log/branch/tag/ref?!
3b5289 37 This is likely an url encoding/decoding problem with forward slashes:
JM 38
39 **bad**
40
41     http://192.168.1.2/log/myrepo.git/refs/heads/master
42
43 **good**
44
45     http://192.168.1.2/log/myrepo.git/refs%2Fheads%2Fmaster
46
47 **NOTE:**  
3cc6e2 48 You can not trust the url in the address bar of your browser since your browser may decode it for presentation.  When in doubt, *View Source* of the generated html to confirm the *href*.
3b5289 49
JM 50 There are two possible workarounds for this issue.  In `gitblit.properties` or `web.xml`:
230632 51
JM 52 1. try setting *web.mountParameters* to *false*.<br/>This changes the url scheme from mounted (*/commit/myrepo.git/abcdef*) to parameterized (*/commit/?r=myrepo.git&h=abcdef*).
53 2. try changing *web.forwardSlashCharacter* to an asterisk or a **!**
7e5ee5 54
3b5289 55 ### Running Gitblit behind mod_proxy or some other proxy layer
JM 56
57 You must ensure that the proxy does not decode and then re-encode request urls with interpretation of forward-slashes (*%2F*).  If your proxy layer does re-encode embedded forward-slashes then you may not be able to browse grouped repositories or logs, branches, and tags **unless** you set *web.mountParameters=false*.
58
3cc6e2 59 If you are using Apache mod_proxy you may have luck with specifying [AllowEncodedSlashes NoDecode](http://httpd.apache.org/docs/2.2/mod/core.html#allowencodedslashes).
70b492 60
486ee1 61 ### Running Gitblit on Tomcat
JM 62
63 Tomcat takes the extra precaution of [disallowing embedded slashes by default](http://tomcat.apache.org/security-6.html#Fixed_in_Apache_Tomcat_6.0.10).  This breaks Gitblit urls.  
64 You have a few options on how to handle this scenario:
65
efba97 66 1. [Tweak Tomcat](http://tomcat.apache.org/security-6.html#Fixed_in_Apache_Tomcat_6.0.10)  
3cc6e2 67 Add *-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true* to *CATALINA_OPTS* or to your JVM launch parameters
486ee1 68 2. *web.mountParameters = false* and use non-pretty, parameterized urls
JM 69 3. *web.forwardSlashCharacter = !* which tells Gitblit to use **!** instead of **/**
70
b34048 71 #### UTF-8 Filenames
JM 72
73 Tomcat also dislikes urls with non-ASCII characters. If your repositories have non-ASCII filenames you will have to modify your connector properties to allow UTF-8 encoded urls.  
74
75 [Tomcat Character Encoding](http://wiki.apache.org/tomcat/FAQ/CharacterEncoding)  
76 [Tomcat Connector Properties](http://tomcat.apache.org/tomcat-6.0-doc/config/http.html)
77
1f9dae 78 ## General Interest Questions
f90dc6 79
f13c4c 80 ### Gitblit?  What kind of name is that?
1f9dae 81 It's a phonetic play on [bitblt][bitblt] which is an image processing operation meaning *bit-block transfer*.
f90dc6 82
f13c4c 83 ### Why use Gitblit?
1f9dae 84 It's a small tool that allows you to easily manage shared repositories and doesn't require alot of setup or git kung-foo.
f90dc6 85
168566 86 ### Who is the target user for Gitblit?
JM 87 Small workgroups that require centralized repositories.
88
89 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.
90
f90dc6 91 ### Do I need real Git?
6c4be1 92 No (mostly).  Gitblit is based on [JGit][jgit] which is a pure Java implementation of the [Git version control system][git].
87066a 93 Everything you need for Gitblit (except Java) is bundled in the distribution file.
d39680 94
3b5289 95 #### mostly
87066a 96 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.
716745 97
168566 98 ### Can I run Gitblit in conjunction with my existing Git tooling?
5450d0 99 Yes.
f90dc6 100
f13c4c 101 ### Do I need a JDK or can I use a JRE?
87066a 102 Gitblit will run just fine with a JRE.
1f9dae 103
f13c4c 104 ### Does Gitblit use a database to store its data?
cc0477 105 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`.
f13c4c 106
cc0477 107 ### Can I manually edit users.conf, gitblit.properties, or .git/config?
1f9dae 108 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`.
JM 109
3b5289 110 **NOTE:**  
JM 111 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.
a4d249 112
6f46fa 113 ### Can I restrict access to branches or paths within a repository?
JM 114 No, not out-of-the-box.  Access restrictions apply to the repository as a whole.
56c549 115
6f46fa 116 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).
JM 117
118 Should you require more fine-grained access controls you might consider writing a Groovy *prereceive* script to block updating branch refs based on some permissions file.  I would be interested in a generic, re-usable script to include with Gitblit, should someone want to implement it.
119
120 Alternatively, you could use [gitolite](https://github.com/sitaramc/gitolite) and SSH for your repository access.
56c549 121
5450d0 122 ### Can I authenticate users against XYZ?
6f46fa 123 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.
5450d0 124
f13c4c 125 ### Why doesn't Gitblit support SSH?
a4d249 126
87066a 127 It will.  This feature is in development and should land in the 1.5.0 release.
f90dc6 128
f13c4c 129 ### What types of Search does Gitblit support?
e4547f 130
JM 131 As of 0.9.0, Gitblit supports Lucene-based searching.
132
6c4be1 133 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*.
f90dc6 134
JM 135 To search by *author* or *committer* use the following syntax in the search box:
136
137     author: james
138     committer: james
139     
140 Alternatively, you could enable the search type dropdown list in your `gitblit.properties` file.
141
831469 142 ### Why did you call the setting federation.N.frequency instead of federation.N.period?!
JM 143
144 Yes, yes I know that you are really specifying the period, but Frequency sounds better to me.  :)
145
716745 146 ### Can Gitblit be translated?
JM 147
148 Yes.  Most messages are localized to a standard Java properties file.
c19ae5 149
f90dc6 150 [bitblt]: http://en.wikipedia.org/wiki/Bit_blit "Wikipedia Bitblt"
JM 151 [jgit]: http://eclipse.org/jgit "Eclipse JGit Site"
a4d249 152 [git]: http://git-scm.com "Official Git Site"
f13c4c 153 [mina]: http://mina.apache.org "Apache Mina"
cc0477 154 [bouncycastle]: http://bouncycastle.org "The Legion of the Bouncy Castle"