Documentation

James Moger

2013-10-25 6c4be170559efa112bb92cd1676543e86850e976

Documentation

Change-Id: I717e13d1f852a4adf50b547f4769dd62da2384ce

 HOME.md

New file
@@ -0,0 +1,40 @@
## Documentation



This documentation is the source content from which the [Gitblit website](http://gitblit.com) is generated.



### About Gitblit



[[src/site/features.mkd]]

[[src/site/design.mkd]]

[[src/site/faq.mkd]]



### Gitblit GO



[[src/site/setup_go.mkd]]

[[src/site/upgrade_go.mkd]]



### Gitblit WAR



[[src/site/setup_war.mkd]]

[[src/site/upgrade_war.mkd]]



### Gitblit Express for OpenShift



[[src/site/setup_express.mkd]]

[[src/site/upgrade_express.mkd]]



### General Configuration & Administration



[[src/site/setup_authentication.mkd]]

[[src/site/setup_client.mkd]]

[[src/site/setup_clientmenus.mkd]]

[[src/site/setup_hooks.mkd]]

[[src/site/setup_lucene.mkd]]

[[src/site/setup_proxy.mkd]]

[[src/site/setup_viewer.mkd]]

[[src/site/administration.mkd]]



### Other Pages



[[src/site/federation.mkd]]

[[src/site/rpc.mkd]]


 README.markdown

@@ -1,13 +1,13 @@
Gitblit

=================



Gitblit is an open source, pure Java Git solution for managing, viewing, and serving [Git](http://git-scm.com) repositories.<br/>

Gitblit is an open source, pure Java Git solution for managing, viewing, and serving [Git](http://git-scm.com) repositories.

More information about Gitblit can be found [here](http://gitblit.com).



License

-------



Gitblit is distributed under the terms of the [Apache Software Foundation license, version 2.0](http://www.apache.org/licenses/LICENSE-2.0).<br/>

Gitblit is distributed under the terms of the [Apache Software Foundation license, version 2.0](http://www.apache.org/licenses/LICENSE-2.0).

The text of the license is included in the file LICENSE in the root of the project.



Java Runtime Requirement

@@ -18,23 +18,23 @@
Getting help

------------



Read the online documentation available at the [Gitblit website](http://gitblit.com)<br/>

Read the online documentation available at the [Gitblit website](http://gitblit.com)

Issues, binaries, & sources @ [Google Code](http://code.google.com/p/gitblit)



Building Gitblit

----------------

[Eclipse](http://eclipse.org) is recommended for development as the project settings are preconfigured.



1. Import the gitblit project into your Eclipse workspace.<br/>

1. Import the gitblit project into your Eclipse workspace.

*There will be lots of build errors.*

2. Using Ant, execute the `build.xml` script in the project root.<br/>

2. Using Ant, execute the `build.xml` script in the project root.

*This will download all necessary build dependencies and will also generate the Keys class for accessing settings.*

3. Select your gitblit project root and **Refresh** the project, this should correct all build problems.

4. Using JUnit, execute the `com.gitblit.tests.GitBlitSuite` test suite.<br/>

4. Using JUnit, execute the `com.gitblit.tests.GitBlitSuite` test suite.

*This will clone some repositories from the web and run through the unit tests.*

5. Execute the *com.gitblit.GitBlitServer* class to start Gitblit GO.



Building Tips & Tricks

----------------------

1. If you are running Ant from an ANSI-capable console, consider setting the `MX_COLOR` ennvironment variable before executing Ant.<pre>set MX_COLOR=true</pre>

1. If you are running Ant from an ANSI-capable console, consider setting the `MX_COLOR` environment variable before executing Ant.<pre>set MX_COLOR=true</pre>

2. The build script will honor your Maven proxy settings.  If you need to fine-tune this, please review the [settings.moxie](http://gitblit.github.io/moxie/settings.html) documentation.

 src/main/resources/gitblit.css

@@ -1512,13 +1512,13 @@
}



div.markdown pre {

    background-color: rgb(251, 251, 251);

    background-color: rgb(250, 250, 250);

    border: 1px solid rgb(221, 221, 221);

    border-radius: 4px 4px 4px 4px;

    display: block;

    font-size: 12px;

    line-height: 18px;

    margin: 0 0 9px;

    margin: 9px 0;

    padding: 8.5px;

    white-space: pre-wrap;

}

@@ -1530,7 +1530,7 @@
}



div.markdown code {

    background-color: rgb(251, 251, 251);

    background-color: rgb(250, 250, 250);

    border: 1px solid rgb(221, 221, 221);

    border-radius: 3px;

    padding: 0 0.2em;


 src/site/administration.mkd

@@ -95,15 +95,15 @@
**How is this enforced?**



Bob must set his *user.name* and *user.email* values for the repository to match his Gitblit user account **BEFORE** committing to his repository.

<pre>



```

[user "bob"]

    displayName = Bob Jones

    emailAddress = bob@somewhere.com

</pre>

<pre>

```



    git config user.name "Bob Jones"

    git config user.email bob@somewhere.com    

</pre>

or



    git config user.name bob


 src/site/faq.mkd

@@ -99,12 +99,12 @@
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/>

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)<br/>

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

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

@@ -112,7 +112,7 @@
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/>

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

@@ -155,7 +155,7 @@


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:




 src/site/federation.mkd

@@ -48,12 +48,13 @@
If you want your repositories (and optionally users accounts and settings) to be pulled by another Gitblit instance, you need to register your origin Gitblit instance with a pulling Gitblit instance by providing the url of your Gitblit instance and a federation token.



Gitblit generates the following standard federation tokens:

---JAVA---



```java

String allToken = SHA1(passphrase + "-ALL");

String usersAndRepositoriesToken = SHA1(passphrase + "-USERS_AND_REPOSITORIES");

String repositoriesToken = SHA1(passphrase + "-REPOSITORIES");

---JAVA---

    
```



The *ALL* token allows another Gitblit instance to pull all your repositories, user accounts, server settings, and referenced push scripts.  

The *USERS_AND_REPOSITORIES* token allows another Gitblit instance to pull all your repositories and  user accounts.  

The *REPOSITORIES* token only allows pulling of the repositories.


 src/site/rpc.mkd

@@ -58,6 +58,7 @@
## JSON Remote Procedure Call (RPC) Interface



### RPC Protocol Versions



<table class="table">

<tbody>

<tr><th>Release</th><th>Protocol Version</th></tr>

@@ -78,6 +79,7 @@
Use *SET_REPOSITORY_TEAM_PERMISSIONS* instead.



### RPC Request and Response Types



<table class="table">

<tr><th colspan='2'>url parameters</th><th rowspan='2'>required<br/>user<br/>permission</th><th rowspan='2'>protocol<br/>version</th><th colspan='2'>json</th></tr>

<tr><th>req=</th><th>name=</th><th>post body</th><th>response body</th></tr>

@@ -120,6 +122,7 @@
</table>



### RPC/HTTP Response Codes



<table class="table">

<tr><th>code</th><th>name</th><th>description</th></tr>

<tr><td>200</td><td>success</td><td>Gitblit processed the request successfully</td></tr>

@@ -134,7 +137,8 @@


**url**: https://localhost/rpc?req=LIST_REPOSITORIES  

**response body**: Map&lt;String, RepositoryModel&gt; where the map key is the clone url of the repository

<pre>



```json

{

  "https://localhost/git/libraries/xmlapache.git": {

    "name": "libraries/xmlapache.git",

@@ -177,7 +181,7 @@
    "size": "4.8 MB"

  }

}

</pre>

```



### Example: EDIT_REPOSITORY (rename)



@@ -185,7 +189,8 @@


**url**: https://localhost/rpc?req=EDIT_REPOSITORY&name=libraries/xmlapache.git  

**post body**: RepositoryModel

<pre>



```json

{

    "name": "libraries/xmlapache-renamed.git",

    "description": "apache xmlrpc client and server",

@@ -207,12 +212,13 @@
    "skipSummaryMetrics": false,

    "size": "102 KB"

}

</pre>

```



### Example: LIST_USERS

**url**: https://localhost/rpc?req=LIST_USERS  

**response body**: List&lt;UserModel&gt;

<pre>



```json

[

  {

    "username": "admin",

@@ -232,12 +238,13 @@
    ]

  }

]

</pre>

```



### Example: LIST_SETTINGS

**url**: https://localhost/rpc?req=LIST_SETTINGS  

**response body**: ServerSettings

<pre>



```json

{

  "settings": {

      "web.siteName": {

@@ -262,12 +269,13 @@
      }

  }

}

</pre>

```



### Example: LIST_STATUS

**url**: https://localhost/rpc?req=LIST_STATUS  

**response body**: ServerStatus

<pre>



```json

{

  "bootDate": "2011-10-22T12:13:00Z",

  "version": "0.7.0-SNAPSHOT",

@@ -294,4 +302,4 @@
  "heapSize": 1899560960,

  "servletContainer": "jetty/7.4.3.v20110701"

}

</pre>
```

 src/site/setup_client.mkd

@@ -35,11 +35,12 @@
#### 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 a Repository 




 src/site/setup_clientmenus.mkd

@@ -7,7 +7,8 @@
You can define new client integrations and deactivate/remove the default integrations by creating a file *$(baseFolder}/clientapps.json*.



### Example definitions

---JSON---



```json

[

    {

        "name": "SmartGit/Hg",

@@ -45,4 +46,4 @@
        "isActive": false

    }

]

---JSON---
```


 src/site/setup_go.mkd

@@ -2,7 +2,7 @@


1. Download and unzip Gitblit GO [${project.releaseVersion} (Windows)](%GCURL%gitblit-${project.releaseVersion}.zip) or [${project.releaseVersion} (Linux/OSX)](%GCURL%gitblit-${project.releaseVersion}.tar.gz).  

*Its best to eliminate spaces in the path name.* 

2. The server itself is configured through a simple text file.<br/>

2. The server itself is configured through a simple text file.

Open `data/gitblit.properties` in your favorite text editor and make sure to review and set:

    - *server.httpPort* and *server.httpsPort*

    - *server.httpBindInterface* and *server.httpsBindInterface*  

@@ -10,10 +10,12 @@
    **https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication!

    - *git.packedGitLimit* (set larger than the size of your largest repository)

    - *git.streamFileThreshold* (set larger than the size of your largest committed file)

3. Execute `authority.cmd` or `java -cp gitblit.jar com.gitblit.authority.Launcher --baseFolder data` from a command-line<br/>**NOTE:** The Authority is a Swing GUI application.  Use of this tool is not required as Gitblit GO will startup and create SSL certificates itself, BUT use of this tool allows you to control the identification metadata used in the generated certificates.  Skipping this step will result in certificates with default metadata.

3. Execute `authority.cmd` or `java -cp gitblit.jar com.gitblit.authority.Launcher --baseFolder data` from a command-line

**NOTE:** The Authority is a Swing GUI application.  Use of this tool is not required as Gitblit GO will startup and create SSL certificates itself, BUT use of this tool allows you to control the identification metadata used in the generated certificates.  Skipping this step will result in certificates with default metadata.

    1. fill out the fields in the *new certificate defaults* dialog

    2. enter the store password used in *server.storePassword* when prompted.  This generates an SSL certificate for **localhost**.

    3. you may want to generate an SSL certificate for the hostname or ip address hostnames you are serving from<br/>**NOTE:** You can only have **one** SSL certificate specified for a port.

    3. you may want to generate an SSL certificate for the hostname or ip address hostnames you are serving from

    **NOTE:** You can only have **one** SSL certificate specified for a port.

    5. exit the authority app

4. Execute `gitblit.cmd` or `java -jar gitblit.jar --baseFolder data` from a command-line

5. Open your browser to <http://localhost:8080> or <https://localhost:8443> depending on your chosen configuration.

@@ -94,20 +96,20 @@
3. Add any necessary *--StartParams* as enumerated below in **Command-Line Parameters**.

4. Execute the script.



After service installation you can use the `gitblitw.exe` utility to control and modify the runtime settings of the service.<br/>

After service installation you can use the `gitblitw.exe` utility to control and modify the runtime settings of the service.

Additional service definition options and runtime capabilities of `gitblitw.exe` (prunmgr.exe) are documented [here](http://commons.apache.org/daemon/procrun.html).



**NOTE:**<br/>

**NOTE:**

If you change the name of the service from *gitblit* you must also change the name of `gitblitw.exe` to match the new service name otherwise the connection between the service and the utility is lost, at least to double-click execution. 



#### VM Considerations

By default, the service installation script configures your Windows service to use your default JVM.  This setup usually defaults to a client VM.<br/>

By default, the service installation script configures your Windows service to use your default JVM.  This setup usually defaults to a client VM.

If you have installed a JDK, you might consider using the `gitblitw.exe` utility to manually specify the *server* VM.



1. Execute `gitblitw.exe`

2. On the *Java* tab uncheck *Use default*.

3. Manually navigate your filesystem and specify the server VM with the `...` button<br/><pre>

Java Virtual Machine:

3. Manually navigate your filesystem and specify the server VM with the `...` button

<pre>Java Virtual Machine:

C:\Program Files\Java\jre6\bin\server\jvm.dll</pre>



#### Command-Line Parameters


 src/site/setup_hooks.mkd

@@ -31,7 +31,7 @@

<blockquote>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 <a href="http://ant.apache.org/ivy">Ivy</a> 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.</blockquote>

---JAVA---
```java
// create and use a primitive array
import org.apache.commons.collections.primitives.ArrayIntList

@@ -42,7 +42,7 @@
ints.add(0, 42)
assert ints.size() == 1
assert ints.get(0) == 42
---JAVA---
```

### Custom Fields


 src/site/setup_proxy.mkd

@@ -5,17 +5,21 @@
Each Linux distribution may vary on the exact configuration of Apache 2.2.  

Here is a sample configuration that works on Debian 7.0 (Wheezy), your distribution may be different.



1. First we need to make sure we have Apache's proxy modules available.  
---FIXED---

### Make sure we have Apache's proxy modules



```

sudo su

cd /etc/apache2/mods-enabled

ln -s ../mods-available/proxy.load proxy.load

ln -s ../mods-available/proxy_balancer.load proxy_balancer.load

ln -s ../mods-available/proxy_http.load proxy_http.load

ln -s ../mods-available/proxy_ajp.load proxy_ajp.load

---FIXED---

2. Then we need to make sure we are configuring Apache to use the proxy modules and to setup the proxied connection from Apache to Gitblit GO or from Apache to your chosen servlet container.  The following snippet is stored as `/etc/apache2/conf.d/gitblit`.  
---FIXED---

```

### Configuring Apache to use the proxy modules



Now we must configure Apache to use the proxy modules and  the proxied connection from Apache to Gitblit GO or from Apache to your chosen servlet container.  The following snippet is stored as `/etc/apache2/conf.d/gitblit`.  


```

# Turn off support for true Proxy behaviour as we are acting as 

# a transparent proxy

ProxyRequests Off

@@ -55,7 +59,8 @@
#RequestHeader set X-Forwarded-Context /



#ProxyPass /gitblit ajp://localhost:8009/gitblit

---FIXED---  
```



**Please** make sure to:  

    1. Review the security of these settings as appropriate for your deployment

    2. Uncomment the *ProxyPass* setting for whichever connection you prefer (http/ajp)


 src/site/setup_war.mkd

@@ -2,7 +2,7 @@


1. Download Gitblit WAR [${project.releaseVersion}](%GCURL%gitblit-${project.releaseVersion}.war) to the webapps folder of your servlet container.  

2. You may have to manually extract the WAR (zip file) to a folder within your webapps folder.

3. By default, the Gitblit webapp is configured through `WEB-INF/data/gitblit.properties`.<br/>

3. By default, the Gitblit webapp is configured through `WEB-INF/data/gitblit.properties`.

Open `WEB-INF/data/gitblit.properties` in your favorite text editor and make sure to review and set:

    - &lt;context-parameter&gt; *git.packedGitLimit* (set larger than the size of your largest repository)

    - &lt;context-parameter&gt; *git.streamFileThreshold* (set larger than the size of your largest committed file)


 src/site/upgrade_go.mkd

@@ -9,12 +9,12 @@


## Upgrading Gitblit GO (pre-1.2.1)

1. Create a `data` folder and copy the following files and folders to it:

    - **users.conf*

    - **users.conf**

    - **projects.conf** *(if you have one)*

    - **gitblit.properties**

    - **serverKeystore.jks**

    - **serverTrustStore.jks**

    - *certs** folder

    - **certs** folder

    - **git** folder

    - **groovy** folder

    - **proposals** folder


 src/site/upgrade_war.mkd

@@ -1,5 +1,5 @@
## Upgrading Gitblit WAR (1.2.1+)

1. Make sure your `WEB-INF/web.xml` *baseFolder* context parameter is not `${contextFolder}/WEB-INF/data`!<br/>

1. Make sure your `WEB-INF/web.xml` *baseFolder* context parameter is not `${contextFolder}/WEB-INF/data`!

If it is, move your `WEB-INF/data` folder to a location writeable by your servlet container.

2. Deploy new WAR

3. Edit the new WAR's `WEB-INF/web.xml` file and set the *baseFolder* context parameter to your external baseFolder.