Mostly stable war build.

James Moger

2011-06-18 5450d08e4cd11176bcc50a5b3d001d291bd8982c

 docs/00_index.mkd

@@ -1,20 +1,19 @@
## Overview

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

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 Version

### Current Release



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

%VERSION% ([go](http://gitblit.com/%GO%)|[war](http://gitblit.com/%WAR%)) based on [%JGIT%][jgit]   (*%BUILDDATE%*)



sources @ [Github][gitbltsrc]



### Design Principles

1. [KISS](http://en.wikipedia.org/wiki/KISS_principle)

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 Git:Blit distribution svelte.  
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.  


### Features

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

### Gitblit Features

- JGit SmartHTTP servlet

- Browser and git client authentication

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

@@ -27,51 +26,59 @@
    </ul>

- Gitweb inspired UI

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

- Administrators may create, edit, or delete users 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

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

- Author and Committer email address display can be controlled

- Markdown view support

- Syntax highlighting

- Customizable regular expression handling for commit messages

- Single text file for server configuration

- Git-notes support

- Branch metrics (uses Google Charts)

- HEAD and branch RSS feeds

- 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 users configuration

- Simple repository stats and activity graph (uses Google Charts)

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



### Gitblit-Go Features

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

- Automatically generates a self-signed certificate for https communications

- Single text file for server configuration



### Limitations

- 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

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



### Caveats

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

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



### Todo List

- Review spots where Git:Blit can cache data instead of abusing the disk

    - stats

    - users.properties access

    - available repositories

    - etc

- Download zip feature

- Site documentation

- Code documentation

- Unit testing

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



### Idea List

- Ticgit activity/timeline

- Ticgit query feature with paging support

- Ticgit ticket change history

- View images on Blob page

- View other binary files on Blob page

- Consider clone remote repository feature

- 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

- Blame feature (waiting for the [JGit][jgit] team to do the hard part)



### License

TBD

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



### Inspirations

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

@@ -79,10 +86,10 @@


## Architecture



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

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



### Bundled Dependencies

The following dependencies are bundled with the Git:Blit zip distribution file.

The following dependencies are bundled with Gitblit.



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

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

@@ -91,7 +98,7 @@
- other icons courtesy of [FatCow Hosting](http://www.fatcow.com/free-icons) (Creative Commons CC-BY)



### Downloaded Dependencies

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

The following dependencies are automatically downloaded by Gitblit-Go (or already bundled with the WAR) from the Apache Maven repository and from the Eclipse Maven repository when Gitblit is launched for the first time.



- [JGit][jgit] (EDL 1.0)

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

@@ -102,12 +109,19 @@
- [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)

- [Rome](http://rome.dev.java.net) (Apache 1.1)

- [jdom](http://www.jdom.org) (Apache-style JDOM license)



### 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)



## Building

## Building from Source

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



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.



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

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

@@ -115,10 +129,20 @@
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. Review the settings in `gitblit.properties` in your project root.<br/>

Make sure you set an appropriate value for *git.repositoriesFolder*. 
6. Execute the *com.gitblit.Launcher* class to start Git:Blit.

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.





## Contributing

Patches welcome in any form.



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



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

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

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

[apachelicense]: http://www.apache.org/licenses/LICENSE-2.0 "Apache License, Version 2.0"