path: root/docs/00_index.mkd

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

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

sources @ [Github][gitbltsrc]

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

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

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

### Caveats
- Gitblit may eat your data.  Use at your own risk.
- Gitblit may have security holes.  Patches welcome.  :)

### Todo List
- Code documentation
- Unit testing
- Update Build.java to JGit 1.0.0, when its released
- WAR solution

### Idea List
- 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

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

### Inspirations
- [Gitweb](http://www.git-scm.com)
- [Fossil](http://www.fossil-scm.org) 

## Architecture

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

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

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

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

- [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)
- [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 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/>
*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.


## 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"
[apachelicense]: http://www.apache.org/licenses/LICENSE-2.0 "Apache License, Version 2.0"