Adjustments to init scripts

James Moger

2012-02-02 a71c5a27e3768cb68b979eac6ec8c7d7612dec8f

 docs/00_index.mkd

@@ -1,146 +1,87 @@
## Overview

Gitblit is an open-source, integrated pure Java stack for managing, viewing, and serving [Git][git] repositories.

Its designed primarily as a tool for small workgroups who want to host [Git][git] repositories on a Windows machine.  Having said that, it works equally well on any standard Linux distribution.

 
### Current Release

## What is Gitblit?

<div class="well" style="margin-left:5px;float:right;width:275px;padding: 10px 10px;">

<b>Current Release %VERSION% (%BUILDDATE%)</b> <a href="releases.html">changelog</a>

<div style="padding:5px;"><a style="width:150px;text-decoration:none;" class="btn success" href="http://code.google.com/p/gitblit/downloads/detail?name=%GO%">Download Gitblit GO</a></div>

<div style="padding:5px;"><a style="width:150px;text-decoration:none;" class="btn danger" href="http://code.google.com/p/gitblit/downloads/detail?name=%WAR%">Download Gitblit WAR</a></div>

<div style="padding:5px;"><a style="width:150px;text-decoration:none;" class="btn info" href="http://code.google.com/p/gitblit/downloads/detail?name=%EXPRESS%">Download Gitblit Express</a> <span class="label warning">BETA</span></div>

<div style="padding:5px;"><a style="width:150px;text-decoration:none;" class="btn primary" href="http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%">Download Gitblit Manager</a></div>

   <div style="text-align:center">

      <a href="http://code.google.com/p/gitblit/downloads/detail?name=%API%">Gitblit API</a> | <a href="http://code.google.com/p/gitblit/downloads/detail?name=%FEDCLIENT%">Gitblit Federation Client</a>

      <br/>

      <a href="screenshots.html" title="Screenshots"><img style="margin-top:5px;border:1px solid #ccc;" src="thumbs/00.png" alt="Screenshots" /></a>

   </div>



[%VERSION%](http://gitblit.com/%DISTRIBUTION%) based on [%JGIT%][jgit] &nbsp; (*%BUILDDATE%*)

   <div style="padding-top:5px;">

   <table class="condensed-table">

      <tbody>

      <tr><th>License</th><td><a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, version 2.0</a></td></tr>

      <tr><th>Sources</th><td><a href="http://github.com/gitblit">GitHub</a> &amp; <a href="http://code.google.com/p/gitblit/source/list">GoogleCode</a></td></tr>		
      <tr><th>Issues</th><td><a href="http://code.google.com/p/gitblit/issues/list">GoogleCode</a></td></tr>

      <tr><th>Discussion</th><td><a href="http://groups.google.com/group/gitblit">Gitblit Group</a></td></tr>

      <tr><th>Google+</th><td><a href="https://plus.google.com/114464678392593421684">Gitblit+</a></td></tr>

      <tr><th>Ohloh</th><td><a target="_top" href="http://www.ohloh.net/p/gitblit"><img border="0" width="100" height="16" src="http://www.ohloh.net/p/gitblit/widgets/project_thin_badge.gif" alt="Ohloh project report for Gitblit" /></a></td></tr>

      <tr><th>Donations</th><td>If you enjoy Gitblit and want to support its development, please consider making a donation to <a href="http://www.helpmegivetostjude.org/gitblit">St. Jude Children's Research Hospital</a>.

      <a href="http://www.helpmegivetostjude.org/gitblit" alt="St. Jude Children's Research Hospital"><img style="padding-top:10px;" src="stjude_150x150.gif"/></a></td></tr>

      </tbody>

      </table>

   </div>

</div>



sources @ [Github][gitbltsrc]

Gitblit is an open-source, pure Java stack for managing, viewing, and serving [Git][git] repositories.  
It's designed primarily as a tool for small workgroups who want to host centralized repositories.



### Design Principles

1. [Keep It Simple, Stupid](http://en.wikipedia.org/wiki/KISS_principle)

2. Offer useful features for serving Git repositories.  If feature is complex, refer to #1.

3. All dependencies must be retrievable from a publicly accessible [Maven](http://maven.apache.org) repository.<br/>This is to ensure authenticity of dependencies and to keep the Gitblit distribution svelte.  
You can browse a live demo [here](http://demo-gitblit.rhcloud.com) hosted on [RedHat's OpenShift][rhcloud] cloud service.



### Features

- Out-of-the-box integrated stack requiring minimal configuration

- JGit SmartHTTP servlet

- Browser and git client authentication

- Four repository access control configurations and a Read-Only flag

    <ul class='noBullets'>

    <li>![anonymous](blank.png) *Anonymous View, Clone & Push*</li>

    <li>![push](lock_go_16x16.png) *Authenticated Push*</li>

    <li>![clone](lock_pull_16x16.png) *Authenticated Clone & Push*</li>

    <li>![view](shield_16x16.png) *Authenticated View, Clone & Push*</li>

    <li>![freeze](cold_16x16.png) Freeze repository (i.e. deny push, make read-only)

    </ul>

- Gitweb inspired UI

- Administrators may create, edit, rename, or delete repositories through the web UI

- Administrators may create, edit, rename, or delete users through the web UI

- Repository Owners may edit repositories through the web UI

- Automatically generates a self-signed certificate for https communications

- Git-notes support

- Branch metrics (uses Google Charts)

- Blame annotations view

- Dates can optionally be displayed using the browser's reported timezone

- Display of Author and Committer email addresses can be disabled

- Case-insensitive searching of commit messages, authors, or committers

- Dynamic zip downloads feature

- Markdown file view support

- Syntax highlighting for popular source code types

- Customizable regular expression substitution for commit messages (i.e. bug or code review link integration)

- Single text file for server configuration

- Single text file for users configuration

- Optional utility pages

    <ul class='noBullets'>

    <li>![docs](book_16x16.png) Docs page which enumerates all Markdown files within a repository</li>

    <li>![tickets](bug_16x16.png) Ticgit ticket pages *(based on last MIT release bf57b032 2009-01-27)*</li>

    </ul>

**NOTE:**  
The demo is a bit unstable due to a bug in JBossAS7/Tomcat when running in LOW_MEMORY mode which OpenShift mandates.  RedHat engineers hope to have this issue resolved soon.



### Limitations

- [%JGIT%][jgit] does not currently [garbage collect or repack](http://www.kernel.org/pub/software/scm/git/docs/git-gc.html)

- HTTP/HTTPS are the only supported protocols

- Access controls are not path-based, they are repository-based

- Only Administrators can create, rename or delete repositories

- Gitblit is an integrated, full-stack solution.  There is no WAR build at this time.

### GO: Single-Stack Solution



### Caveats

- Gitblit may eat your data.  Use at your own risk.

- Gitblit may have security holes.  Patches welcome.  :)

*Gitblit GO* is an integrated, single-stack solution based on Jetty.



### Todo List

- Code documentation

- Unit testing

- Update Build.java to JGit 1.0.0, when its released

You do not need Apache httpd, Perl, Git, or Gitweb.  Should you want to use some or all of those, you still can; Gitblit plays nice with the other kids on the block.



### Idea List

- Consider clone remote repository feature

- Consider [Apache Shiro](http://shiro.apache.org) for authentication

- Stronger Ticgit read-only integration

    - activity/timeline

    - query feature with paging support

    - change history

- Ticgit write integration

- Blob page improvements

    - view images

    - view other binary files (pdf, doc, etc)

- Markdown editing feature

This is what you should download if you want to go from zero to Git in less than 5 mins.



### License

Gitblit is distributed under the terms of the [Apache Software Foundation license, version 2.0][apachelicense]

All dependencies are bundled.



### Inspirations

- [Gitweb](http://www.git-scm.com)

- [Fossil](http://www.fossil-scm.org) 
### WAR: For Your Servlet Container

*Gitblit WAR* is what you should download if you already have a servlet container available that you wish to use.  Jetty 6/7/8 and Tomcat 6/7 are known to work.  Generally, any Servlet 2.5 or Servlet 3.0 container should work.



## Architecture

All dependencies are bundled.



![block diagram](architecture.png "Gitblit Architecture")

### Express: For the Cloud <span class="label warning" style="vertical-align: middle;">BETA</span>

*Gitblit Express* is a prepared distribution for [RedHat's OpenShift][rhcloud] cloud service.



### Bundled Dependencies

The following dependencies are bundled with the Gitblit zip distribution file.

All dependencies are bundled.



- [google-code-prettify](http://code.google.com/p/google-code-prettify) (Apache 2.0)

- [JavaService](http://forge.ow2.org/projects/javaservice) (BSD and LGPL)

- magnifying glass search icon courtesy of [Gnome](http://gnome.org) (Creative Commons CC-BY)

- modified Git logo originally designed by [Henrik Nyh](http://henrik.nyh.se/2007/06/alternative-git-logo-and-favicon)

- other icons courtesy of [FatCow Hosting](http://www.fatcow.com/free-icons) (Creative Commons CC-BY)

### You decide how to use Gitblit



### Downloaded Dependencies

The following dependencies are automatically downloaded from the Apache Maven repository and from the Eclipse Maven repository when Gitblit is launched for the first time.

Gitblit can be used as a dumb repository viewer with no administrative controls or user accounts.  
Gitblit can be used as a complete Git stack for cloning, pushing, and repository access control.  
Gitblit can be used without any other Git tooling (including actual Git) or it can cooperate with your established tools.



- [JGit][jgit] (EDL 1.0)

- [Wicket](http://wicket.apache.org) (Apache 2.0)

- [WicketStuff GoogleCharts](https://github.com/wicketstuff/core/wiki/GoogleCharts) (Apache 2.0)

- [MarkdownPapers](http://markdown.tautua.org) (Apache 2.0)

- [Jetty](http://eclipse.org/jetty) (Apache 2.0, EPL 1.0)

- [SLF4J](http://www.slf4j.org) (MIT/X11)

- [Log4j](http://logging.apache.org/log4j) (Apache 2.0) 
- [JCommander](http://jcommander.org) (Apache 2.0)

- [BouncyCastle](http://www.bouncycastle.org) (MIT/X11)

- [JSch - Java Secure Channel](http://www.jcraft.com/jsch) (BSD)

### Easy Remote Management



### Other Build Dependencies

- [Fancybox image viewer](http://fancybox.net) (MIT and GPL dual-licensed)

- [JUnit](http://junit.org) (Common Public License)

- [commons-net](http://commons.apache.org/net) (Apache 2.0)

Administrators can create and manage all repositories, user accounts, and teams from the *Web UI*.  
Administrators can create and manage all repositories, user accounts, and teams from the *JSON RPC interface* using the [Gitblit Manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%) or your own custom tooling. 


## Building from Source

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

### Integration with Your Infrastructure



Additionally, [Google CodePro AnalytiX](http://code.google.com/javadevtools), [eclipse-cs](http://eclipse-cs.sourceforge.net), [FindBugs](http://findbugs.sourceforge.net), and [EclEmma](http://www.eclemma.org) are recommended development tools.

- Groovy push hook scripts

- Pluggable user service mechanism for custom authentication, authorization, and user management

- Rich RSS feeds

- JSON-based RPC mechanism

- [Java Client RSS/JSON API library](http://code.google.com/p/gitblit/downloads/detail?name=%API%) for custom integration



1. Clone the git repository from [Github][gitbltsrc].

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

*There will be lots of build errors.*

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

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

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

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

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

5. Review the settings in `gitblit.properties` in your project root.

    - By default, the *git.repositoriesFolder* points to the repositories cloned by the test suite.<br/>

    - If running on Linux you may have to change the served port(s) to > 1024 unless you are developing as the root user. 
6. Execute the *com.gitblit.Launcher* class to start Gitblit.

### Backup Strategy



Gitblit includes a backup mechanism (*federation*) which can be used to backup repositories and, optionally, user accounts, team definitions, server settings, & Groovy push hook scripts from your Gitblit instance to another Gitblit instance or to a [Gitblit Federation Client](http://code.google.com/p/gitblit/downloads/detail?name=%FEDCLIENT%).  Similarly, you can use the federation mechanism to aggregate individual workspace Gitblit instances to a common, centralized server.



## Contributing

Patches welcome in any form.

### Java Runtime Requirement



Contributions must be your own original work and must licensed under the [Apache License, Version 2.0][apachelicense], the same license used by Gitblit.

Gitblit requires a Java 6 Runtime Environment (JRE) or a Java 6 Development Kit (JDK).



[jgit]: http://eclipse.org/jgit "Eclipse JGit Site"

[git]: http://git-scm.com "Official Git Site"

[gitbltsrc]: http://somewhere.com "gitblit git repository"

[apachelicense]: http://www.apache.org/licenses/LICENSE-2.0 "Apache License, Version 2.0"
[rhcloud]: https://openshift.redhat.com/app "RedHat OpenShift"