Gitblit devel
blame | history | patch | commit | commitdiff | ignore whitespace
James Moger
2011-10-21 4d44cf806ddfa8d051f2d6b1289fa3b67b0daf2e 
 docs/00_index.mkd


@@ -1,123 +1,63 @@


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



 


<a href="screenshots.html" title="Screenshots"><img class="overview" src="thumbs/00.png" alt="Screenshots" /></a>







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



Its designed primarily as a tool for small workgroups who want to host centralized repositories.







Gitblit is available in two variations:







1. *Gitblit GO* - a complete & integrated pure Java stack



    


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


    Gitblit GO is like a mashup of Apache httpd, [Git][git], and Gitweb with simplified configuration and maintenance.  


    All dependencies are downloaded on first execution.



2. *Gitblit WAR* - a traditional WAR distribution



    


    This is what you should download if you want to deploy Gitblit into your own servlet container (e.g. Tomcat, Jetty, etc).  


    All dependencies are bundled.







### Tools







- *Gitblit Manager* - a Java/Swing application for remote administration of a Gitblit server



- *Gitblit Federation Client* - a command line tool to clone/pull groups of repositories and optionally users and settings







### Java Runtime Requirement







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







### Current Release







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



**%VERSION%** ([go](http://code.google.com/p/gitblit/downloads/detail?name=%GO%)|[war](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%)|[fedclient](http://code.google.com/p/gitblit/downloads/detail?name=%FEDCLIENT%)|[manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%)) based on [%JGIT%][jgit] &nbsp; *released %BUILDDATE%*







- improved: updated ui with Twitter's Bootstrap CSS toolkit  


    **New:** *web.loginMessage = gitblit*



- improved: repositories list performance by caching repository sizes (issue 27)



- improved: summary page performance by caching metric calculations (issue 25)



- added: authenticated JSON RPC mechanism   


    **New:** *web.enableRpcServlet = true*  


    **New:** *web.enableRpcAdministration = false*



- added: reusable JSON RPC client class



- added: Gitblit Manager (Java/Swing Application) for remote administration of a Gitblit server.



- fixed: federation protocol timestamps.  dates are now serialized to the [iso8601](http://en.wikipedia.org/wiki/ISO_8601) standard.  


    **This breaks 0.6.0 federation clients/servers.**



- fixed: Gitblit can now browse the Linux kernel repository (issue 25)



- fixed: Gitblit now runs on Servlet 3.0 webservers (e.g. Tomcat 7, Jetty 8) (issue 23)



- fixed: Set the RSS content type for Firefox 4 (issue 22)



- fixed: Null pointer exception if did not set federation strategy (issue 20)



- fixed: Gitblit GO allows SSL renegotiation if running on Java 1.6.0_22 or later



- added: IUserService.setup(IStoredSettings) for custom user service implementations



- added: setting to control Gitblit GO context path for proxy setups  


    **New:** *server.contextPath = /*



- updated: MarkdownPapers 1.2.4







issues, binaries, and sources @ [Google Code][googlecode]<br/>



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



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



- Author and Committer email address display can be controlled



- Dynamic zip downloads feature



- Markdown view support



- Syntax highlighting



- Customizable regular expression handling for commit messages



- Single text file for server configuration



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







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



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







### Todo List



- Review spots where Gitblit can cache data instead of abusing the disk



    - stats



    - users.properties access



    - available repositories



    - etc



- Code documentation



- Unit testing







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



- Markdown editing feature



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







### License



Licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)







### Inspirations



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



- [Fossil](http://www.fossil-scm.org) 






## Architecture







![block diagram](architecture.png "Git Blit 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)







### Other Build Dependencies



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







## Building



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







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



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







[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://github.com/gitblit "gitblit git repository"



[googlecode]: http://code.google.com/p/gitblit "gitblit project management"



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