gitblit/docs/00_index.mkd

Overview

Gitblit is an open-source, integrated pure Java stack for managing, viewing, and serving Git repositories. Its designed primarily as a tool for small workgroups who want to host Git repositories on a Windows machine. Having said that, it works equally well on any standard Linux distribution.

Current Release

%VERSION% based on %JGIT%   (%BUILDDATE%)

sources @ Github

Design Principles

1. Keep It Simple, Stupid
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 repository.
   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
  • Anonymous View, Clone & Push
  • Authenticated Push
  • Authenticated Clone & Push
  • Authenticated View, Clone & Push
  • Freeze repository (i.e. deny push, make read-only)
• 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
  • Docs page which enumerates all Markdown files within a repository
  • Ticgit ticket pages (based on last MIT release bf57b032 2009-01-27)

Limitations

• %JGIT% does not currently garbage collect or repack
• 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

• Custom BASIC authentication servlet or servlet filter
• Code documentation
• Unit testing
• Update Build.java to JGit 1.0.0, when its released

Idea List

• Consider clone remote repository feature
• Consider Apache Shiro 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

License

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

Inspirations

• Gitweb
• Fossil

Architecture

Bundled Dependencies

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

• google-code-prettify (Apache 2.0)
• JavaService (BSD and LGPL)
• magnifying glass search icon courtesy of Gnome (Creative Commons CC-BY)
• modified Git logo originally designed by Henrik Nyh
• other icons courtesy of FatCow Hosting (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 (EDL 1.0)
• Wicket (Apache 2.0)
• WicketStuff GoogleCharts (Apache 2.0)
• MarkdownPapers (Apache 2.0)
• Jetty (Apache 2.0, EPL 1.0)
• SLF4J (MIT/X11)
• Log4j (Apache 2.0)
• JCommander (Apache 2.0)
• BouncyCastle (MIT/X11)
• JSch - Java Secure Channel (BSD)
• Rome (Apache 1.1)
• jdom (Apache-style JDOM license)

Other Build Dependencies

• Fancybox image viewer (MIT and GPL dual-licensed)
• JUnit (Common Public License)
• commons-net (Apache 2.0)

Building from Source

Eclipse is recommended for development as the project settings are preconfigured.

Additionally, Google CodePro AnalytiX, eclipse-cs, FindBugs, and EclEmma are recommended development tools.

1. Clone the git repository from Github.
2. Import the gitblit project into your Eclipse workspace.
   There will be lots of build errors.
3. 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.
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.
   This will clone some repositories from the web and run through the unit tests.
6. Review the settings in gitblit.properties in your project root.
   • By default, the git.repositoriesFolder points to the repositories cloned by the test suite.
     
   • If running on Linux you may have to change the served port(s) to > 1024 unless you are developing as the root user.
7. 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, the same license used by Gitblit.