## Troubleshooting
### Eclipse/Egit/JGit complains that it "can't open upload pack"?
There are a few ways this can occur:
1. Are you running Java 7?
Java 7 introduced SNI support for SSL connections and it is enabled by default.
[Java 7 Security Enhancements](http://docs.oracle.com/javase/7/docs/technotes/guides/security/enhancements-7.html)
To disable SNI alerts, add this line to your eclipse.ini file and restart Eclipse.
-Djsse.enableSNIExtension=false
2. 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. Key = http.sslVerify
Value = false
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.
This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*.
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. :(
### I can not push using git:// protocol on Windows using native Git
This is a long-standing, known bug in the native Git for Windows implementation.
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*.
2. Please see the above answer about "**can't open upload pack**".
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.
### How do I run Gitblit GO on port 80 or 443 in Linux?
Linux requires root permissions to serve on ports < 1024.
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?!
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 <context-param> *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 <context-param> *realm.userService* value in your `web.xml` file actually points to a `users.conf` file.
### 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:
**bad**
http://192.168.1.2/log/myrepo.git/refs/heads/master
**good**
http://192.168.1.2/log/myrepo.git/refs%2Fheads%2Fmaster
**NOTE:**
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*.
There are two possible workarounds for this issue. In `gitblit.properties` or `web.xml`:
1. try setting *web.mountParameters* to *false*.
This changes the url scheme from mounted (*/commit/myrepo.git/abcdef*) to parameterized (*/commit/?r=myrepo.git&h=abcdef*).
2. try changing *web.forwardSlashCharacter* to an asterisk or a **!**
### Running Gitblit behind mod_proxy or some other proxy layer
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*.
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).
### Running Gitblit on Tomcat
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.
You have a few options on how to handle this scenario:
1. [Tweak Tomcat](http://tomcat.apache.org/security-6.html#Fixed_in_Apache_Tomcat_6.0.10)
Add *-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true* to *CATALINA_OPTS* or to your JVM launch parameters
2. *web.mountParameters = false* and use non-pretty, parameterized urls
3. *web.forwardSlashCharacter = !* which tells Gitblit to use **!** instead of **/**
#### UTF-8 Filenames
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.
[Tomcat Character Encoding](http://wiki.apache.org/tomcat/FAQ/CharacterEncoding)
[Tomcat Connector Properties](http://tomcat.apache.org/tomcat-6.0-doc/config/http.html)
## General Interest Questions
### Gitblit? What kind of name is that?
It's a phonetic play on [bitblt][bitblt] which is an image processing operation meaning *bit-block transfer*.
### Why use Gitblit?
It's a small tool that allows you to easily manage shared repositories and doesn't require alot of setup or git kung-foo.
### Who is the target user for Gitblit?
Small workgroups that require centralized repositories.
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.
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)
Parsing command-line output is fragile and suboptimal.
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.
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].
Everything you need for Gitblit (except Java) is either bundled in the distribution file or automatically downloaded on execution.
#### 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.
### 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.
### 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` or whatever filename is configured in `gitblit.properties`.
### 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.
Exceptions to this are noted in `gitblit.properties`.
**NOTE:**
Care must be taken to preserve the relationship between user roles and repository names.
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.
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).
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.
Alternatively, you could use [gitolite](https://github.com/sitaramc/gitolite) and SSH for your repository access.
### 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).
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*.
To search by *author* or *committer* use the following syntax in the search box:
author: james
committer: james
Alternatively, you could enable the search type dropdown list in your `gitblit.properties` file.
### Why did you call the setting federation.N.frequency instead of federation.N.period?!
Yes, yes I know that you are really specifying the period, but Frequency sounds better to me. :)
### Can Gitblit be translated?
Yes. Most messages are localized to a standard Java properties file.
[bitblt]: http://en.wikipedia.org/wiki/Bit_blit "Wikipedia Bitblt"
[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"
href='#n153'>153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
|