Troubleshooting

push failed for branch (n/a (unpacker error))

This is a bug in JGit (issue 704). 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:

1. Are you running Java 7?
   Java 7 introduced SNI support for SSL connections and it is enabled by default.
   Java 7 Security Enhancements
   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 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. :(

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 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 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 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:

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.

Running Gitblit on Tomcat

Tomcat takes the extra precaution of disallowing embedded slashes by default. This breaks Gitblit urls.
You have a few options on how to handle this scenario:

1. Tweak Tomcat
   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
Tomcat Connector Properties

General Interest Questions

Gitblit? What kind of name is that?

It's a phonetic play on 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 or Bitbucket with 100s or 1000s of users. Gitblit is designed to fulfill the same function as your centralized Subversion or CVS server.

Do I need real Git?

No (mostly). Gitblit is based on JGit which is a pure Java implementation of the Git version control system.
Everything you need for Gitblit (except Java) is bundled in the distribution file.

mostly

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.

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 page for details.

Can I restrict access to branches or paths within a repository?

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.

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 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.

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.