Java Virtual Machine: C:\Program Files\Java\jre6\bin\server\jvm.dll#### Command-Line Parameters Command-Line parameters override the values in `gitblit.properties` at runtime. --baseFolder The default base folder for all relative file reference settings --repositoriesFolder Git Repositories Folder --userService Authentication and Authorization Service (filename or fully qualified classname) --useNio Use NIO Connector else use Socket Connector. --httpPort HTTP port for to serve. (port <= 0 will disable this connector) --httpsPort HTTPS port to serve. (port <= 0 will disable this connector) --ajpPort AJP port to serve. (port <= 0 will disable this connector) --alias Alias in keystore of SSL cert to use for https serving --storePassword Password for SSL (https) keystore. --shutdownPort Port for Shutdown Monitor to listen on. (port <= 0 will disable this monitor) --tempFolder Folder for server to extract built-in webapp **Example** java -jar gitblit.jar --userService c:/myrealm.config --storePassword something --baseFolder c:/data #### Overriding Gitblit GO's Log4j Configuration You can override Gitblit GO's default Log4j configuration with a command-line parameter to the JVM. java -Dlog4j.configuration=file:///home/james/log4j.properties -jar gitblit.jar
[user "bob"] displayName = Bob Jones emailAddress = bob@somewhere.com
git config user.name "Bob Jones" git config user.email bob@somewhere.comor git config user.name bob git config user.email bob@somewhere.com If the Gitblit account does not specify an email address, then the committer email address is ignored. However, if the account does specify an address it must match the committer's email address. Display name or username can be used as the committer name. All checks are case-insensitive. **What about merges?** You can not use fast-forward merges on your client when using committer verification. You must specify *--no-ff* to ensure that a merge commit is created with your identity as the committer. Only the first parent chain is traversed when verifying commits. #### Push Log Gitblit v1.2.1 introduces an incomplete push mechanism. All pushes are logged since 1.2.1, but the log has not yet been exposed through the web ui. This will be a feature of an upcoming release. ### Teams Since v0.8.0, Gitblit supports *teams* for the original `users.properties` user service and the current default user service `users.conf`. Teams have assigned users and assigned repositories. A user can be a member of multiple teams and a repository may belong to multiple teams. This allows the administrator to quickly add a user to a team without having to keep track of all the appropriate repositories. ### Administering Users (users.conf, Gitblit v0.8.0+) All users are stored in the `users.conf` file or in the file you specified in `gitblit.properties`. Your file extension must be *.conf* in order to use this user service. The `users.conf` file uses a Git-style configuration format: [user "admin"] password = admin role = "#admin" role = "#notfederated" repository = RW+:repo1.git repository = RW+:repo2.git [user "hannibal"] password = bossman repository = RWD:topsecret.git repository = RW+:ateam/[A-Za-z0-9-~_\\./]+ [user "faceman"] password = vanity [user "murdock"] password = crazy [user "babaracus"] password = grrrr [team "ateam"] user = hannibal user = faceman user = murdock user = babaracus repository = RW:topsecret.git mailingList = list@ateam.org postReceiveScript = sendmail The `users.conf` file allows flexibility for adding new fields to a UserModel object that the original `users.properties` file does not afford without imposing the complexity of relying on an embedded SQL database. ### Administering Users (users.properties, Gitblit v0.5.0 - v0.7.0) All users are stored in the `users.properties` file or in the file you specified in `gitblit.properties`. Your file extension must be *.properties* in order to use this user service. The format of `users.properties` loosely follows Jetty's convention for HashRealms: username=password,role1,role2,role3... @teamname=&mailinglist,!username1,!username2,!username3,repository1,repository2,repository3... ### Usernames Usernames must be unique and are case-insensitive. Whitespace is illegal. ### Passwords User passwords are CASE-SENSITIVE and may be *plain*, *md5*, or *combined-md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*). ### User Roles There are four actual *roles* in Gitblit: - *#admin*, which grants administrative powers to that user - *#notfederated*, which prevents an account from being pulled by another Gitblit instance - *#create*, which allows the user the power to create personal repositories - *#fork*, which allows the user to create a personal fork of an existing Gitblit-hosted repository Administrators automatically have access to all repositories. All other *roles* are repository permissions. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository. **NOTE:** The following roles are equivalent: - myrepo.git - RW+:myrepo.git This is to preserve backwards-compatibility with Gitblit <= 1.1.0 which granted rewind power to all access-permitted users. ### Personal Repositories & Forks Personal Repositories and Forks are related but are controlled individually. #### Creating a Personal Repository A user may be granted the power to create personal repositories by specifying the *#create* role through the web ui or through the RPC mechanism via the Gitblit Manager. Personal repositories are exactly like common/shared repositories except that the owner has a few additional administrative powers for that repository, like rename and delete. #### Creating a Fork A user may also be granted the power to fork an existing repository hosted on your Gitblit server to their own personal clone by specifying the *#fork* role through the web ui or via the Gitblit Manager. Forks are mostly likely personal repositories or common/shared repositories except for two important differences: 1. Forks inherit a view/clone access list from the origin repository. i.e. if Team A has clone access to the origin repository, then by default Team A also has clone access to the fork. This is to facilitate collaboration. 2. Forks are always listed in the fork network, regardless of any access restriction set on the fork. In other words, if you fork *RepoA.git* to *~me/RepoA.git* and then set the access restriction of *~me/RepoA.git* to *Authenticated View, Clone, & Push* your fork will still be listed in the fork network for *RepoA.git*. If you really must have an invisible fork, the clone it locally, create a new personal repository for your invisible fork, and push it back to that personal repository. ## Alternative Authentication and Authorization ### LDAP Authentication *SINCE 1.0.0* LDAP can be used to authenticate Users and optionally control Team memberships. When properly configured, Gitblit will delegate authentication to your LDAP server and will cache some user information in the usual users file (.conf or .properties). When using the LDAP User Service, new user accounts can not be manually created from Gitblit. Gitblit user accounts are automatically created for new users on their first succesful authentication through Gitblit against the LDAP server. It is also important to note that the LDAP User Service does not retrieve or store user passwords nor does it implement any LDAP-write functionality. To use the *LdapUserService* set *realm.userService=com.gitblit.LdapUserService* in your `gitblit.properties` file or your `web.xml` file and then configure the *realm.ldap* settings appropriately for your LDAP environment. #### Example LDAP Layout ![block diagram](ldapSample.png "LDAP Sample") Please see [ldapUserServiceSampleData.ldif](https://github.com/gitblit/gitblit/blob/master/tests/com/gitblit/tests/resources/ldapUserServiceSampleData.ldif) to see the data in LDAP that reflects the above picture. #### Gitblit Settings for Example LDAP Layout The following are the settings required to configure Gitblit to authenticate against the example LDAP server with LDAP-controlled team memberships.
parameter | value | description |
---|---|---|
realm.ldap.server | ldap://localhost:389 | Tells Gitblit to connect to the LDAP server on localhost port 389. The URL Must be of form ldap(s)://<server>:<port> with port being optional (389 for ldap, 636 for ldaps). |
realm.ldap.username | cn=Directory Manager | The credentials that will log into the LDAP server |
realm.ldap.password | password | The credentials that will log into the LDAP server |
realm.ldap.backingUserService | users.conf | Where to store all information that is used by Gitblit. All information will be synced here upon user login. |
realm.ldap.maintainTeams | true | Are team memberships maintained in LDAP (true) or manually in Gitblit (false). |
realm.ldap.accountBase | OU=Users,OU=UserControl,OU=MyOrganization,DC=MyDomain | What is the root node for all users in this LDAP system. Subtree searches will start from this node. |
realm.ldap.accountPattern | (&(objectClass=person)(sAMAccountName=${username})) | The LDAP search filter that will match a particular user in LDAP. ${username} will be replaced with whatever the user enters as their username in the Gitblit login panel. |
realm.ldap.groupBase | OU=Groups,OU=UserControl,OU=MyOrganization,DC=MyDomain | What is the root node for all teams in this LDAP system. Subtree searches will start from this node. |
realm.ldap.groupMemberPattern | (&(objectClass=group)(member=${dn})) | The LDAP search filter that will match all teams for the authenticating user. ${username} will be replaced with whatever the user enters as their username in the Gitblit login panel. Anything else in ${} will be replaced by Attributes from the User node. |
realm.ldap.admins | @Git_Admins | A space-delimited list of usernames and/or teams that indicate admin status in Gitblit. Teams are referenced with a leading @ character. |
Grape (The Groovy Adaptable Packaging Engine or Groovy Advanced Packaging Engine) is the infrastructure enabling the grab() calls in Groovy, a set of classes leveraging Ivy to allow for a repository driven module system for Groovy. This allows a developer to write a script with an essentially arbitrary library requirement, and ship just the script. Grape will, at runtime, download as needed and link the named libraries and all dependencies forming a transitive closure when the script is run from existing repositories such as Ibiblio, Codehaus, and java.net.---JAVA--- // create and use a primitive array import org.apache.commons.collections.primitives.ArrayIntList @Grab(group='commons-primitives', module='commons-primitives', version='1.0') def createEmptyInts() { new ArrayIntList() } def ints = createEmptyInts() ints.add(0, 42) assert ints.size() == 1 assert ints.get(0) == 42 ---JAVA--- ### Custom Fields *SINCE 1.0.0* Gitblit allows custom repository string fields to be defined in `gitblit.properties` or `web.xml`. Entry textfields are automatically created for these fields in the Edit Repository page of Gitblit and the Edit Repository dialog of the Gitblit Manager. These fields are accessible from your Groovy hook scripts as repository.customFields.myField This feature allows you to customize the behavior of your hook scripts without hard-coding values in the hook scripts themselves. ### Pre-Receive Pre-Receive scripts execute after the pushed objects have all been written to the Git repository but before the refs have been updated to point to these new objects. This is the appropriate point to block a push and is how many Git tools implement branch-write permissions. ### Post-Receive Post-Receive scripts execute after all refs have been updated. This is the appropriate point to trigger continuous integration builds or send email notifications, etc. ## Push Email Notifications Gitblit implements email notifications in *sendmail.groovy* which uses the Groovy Hook Script mechanism. This allows for dynamic customization of the notification process at the installation site and serves as an example push script. ### Enabling Push Notifications In order to send email notifications on a push to Gitblit, this script must be specified somewhere in the *post-receive* script chain. You may specify *sendmail* in one of three places: 1. *groovy.postReceiveScripts* in `gitblit.properties` or `web.xml`, globally applied to all repositories 2. post-receive scripts of a Team definition 3. post-receive scripts of a Repository definition ### Destination Addresses Gitblit does not currently support individual subscriptions to repositories; i.e. a *user* can not subscribe or unsubscribe from push notifications. However, Repository Managers and Administrators can specify subscribed email addresses in one of three places: 1. *mail.mailingLists* in `gitblit.properties` or `web.xml`, globally applied to all push-notified repositories 2. mailing lists in a Team definition, applied to all repositories that are part of the team definition 3. mailing lists in a Repository definition All three sources are checked and merged into a unique list of destination addresses for push notifications. **NOTE:** Care should be taken when devising your notification scheme as it relates to any VIEW restricted repositories you might have. Setting a global mailing list and activating push notifications for a VIEW restricted repository may send unwanted emails. ## Lucene Search Integration *SINCE 0.9.0* Repositories may optionally be indexed using the Lucene search engine. The Lucene search offers several advantages over commit-traversal search: 1. very fast commit and blob searches 2. multi-term searches 3. term-highlighted and syntax-highlighted fragment matches 4. multi-repository searches ### How do I use it? First you must ensure that *web.allowLuceneIndexing* is set *true* in `gitblit.properties` or `web.xml`. Then you must understand that Lucene indexing is an opt-in feature which means that no repositories are automatically indexed. Like anything else, this design has pros and cons. #### Pros 1. no wasted cycles indexing repositories you will never search 2. you specify exactly what branches are indexed; experimental/dead/personal branches can be ignored #### Cons 1. you specify exactly what branches are indexed #### I have 300 repositories and you want me to specify indexed branches on each one?? Yeah, I agree that is inconvenient. If you are using Gitblit GO there is a utility script `add-indexed-branch.cmd` which allows you to specify an indexed branch for many repositories in one step. If you are using Gitblit WAR then, at present, you are out of luck unless you write your own script to traverse your repositories and use native Git to manipulate each repository config. git config --add gitblit.indexBranch "default" git config --add gitblit.indexBranch "refs/heads/master" #### Indexing Branches You may specify which branches should be indexed per-repository in the *Edit Repository* page. New/empty repositories may only specify the *default* branch which will resolve to whatever commit HEAD points to or the most recently updated branch if HEAD is unresolvable. Indexes are built and incrementally updated on a 2 minute cycle so you may have to wait a few minutes before your index is built or before your latest pushes get indexed. **NOTE:** After specifying branches, only the content from those branches can be searched via Gitblit. Gitblit will automatically redirect any queries entered on a repository's search box to the Lucene search page. Repositories that do not specify any indexed branches will use the traditional commit-traversal search. #### Adequate Heap The initial indexing of an existing repository can potentially exhaust the memory allocated to your Java instance and may throw OutOfMemory exceptions. Be sure to provide your Gitblit server adequate heap space to index your repositories. The heap is set using the *-Xmx* JVM parameter in your Gitblit launch command (e.g. -Xmx1024M). #### Why does Gitblit check every 2 mins for repository/branch changes? Gitblit has to balance its design as a complete, integrated Git server and its utility as a repository viewer in an existing Git setup. Gitblit could build indexes immediately on *edit repository* or on *receiving pushes*, but that design would not work if someone is pushing via ssh://, git://, or file:// (i.e. not pushing to Gitblit http(s)://). For this reason Gitblit has a polling mechanism to check for ref changes every 2 mins. This design works well for all use cases, aside from adding a little lag in updating the index. ## Client Setup and Configuration ### Https with Self-Signed Certificates You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations. **NOTE:** The default self-signed certificate generated by Gitlbit GO is bound to *localhost*. If you are using Eclipse/EGit/JGit clients, you will have to generate your own certificate that specifies the exact hostname used in your clone/push url. You must do this because Eclipse/EGit/JGit (< 3.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting. - **Eclipse/EGit/JGit** 1. Window->Preferences->Team->Git->Configuration 2. Click the *New Entry* button 3.
Key = http.sslVerify Value = false- **Command-line Git** ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
git config --global --bool --add http.sslVerify false### Http Post Buffer Size You may find the default post buffer of your git client is too small to push large deltas to Gitblit. Sometimes this can be observed on your client as *hanging* during a push. Other times it can be observed by git erroring out with a message like: error: RPC failed; result=52, HTTP code = 0. This can be adjusted on your client by changing the default post buffer size:
git config --global http.postBuffer 524288000### Disabling SNI You may run into SNI alerts (Server Name Indication). These will manifest as failures to clone or push to your Gitblit instance. #### Java-based Clients When using Java 7-based clients, SNI is enabled by default. You can disable SNI by specifying the JVM system parameter `-Djsse.enableSNIExtension=false` when your Java-based client launches. For Eclipse, you can append `-Djsse.enableSNIExtension=false` to your *eclipse.ini* file. #### Native Clients Native clients may display an error when attempting to clone or push that looks like this: ---FIXED--- C:\projects\git\gitblit>git push rhcloud master error: error:14077458:SSL routines:SSL23_GET_SERVER_HELLO:reason(1112) while accessing https://demo-gitblit.rhcloud.com/git/gitblit.git/info/refs?service=git-receive-pack fatal: HTTP request failed ---FIXED--- ### Cloning an Access Restricted Repository - **Eclipse/EGit/JGit** Nothing special to configure, EGit figures out everything.
https://yourserver/git/your/repository- **Command-line Git** My testing indicates that your username must be embedded in the url. YMMV.
https://username@yourserver/git/your/repository