Documentation.

James Moger

2011-11-09 da0c3147ce889db5f41675eb930bd8c144cac5f3

Documentation.

 docs/01_features.mkd

@@ -1,4 +1,35 @@
## Gitblit Features

## Why Gitblit?



### Single-Stack Solution



*Gitblit GO* is an integrated, single-stack solution for serving and browsing Git repositories with a per-repository authentication and authorization mechanism.  
You do not need Apache httpd, Perl, Git, Gitweb, or Gitolite.  Should you want to use some or all of those, you still can; Gitblit plays nice with the other kids on the block.  It should be noted that Gitblit does not currently offer fine-grained access controls like [Gitolite](http://sitaramc.github.com/gitolite).



*Gitblit WAR = Gitblit GO - integrated Jetty*  
You provide the servlet container (e.g. Tomcat, Resin, etc) and deploy the WAR like any other webapp.  Gitblit WAR offers all the same capabilities as the GO integrated stack except as noted below. 


### You decide how to use Gitblit



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.



### Easy Web Management



Administrators can create and manage all repositories & user accounts from the *web UI*.  
Administrators can create and manage all repositories & user accounts from the *JSON RPC interface* using the [Gitblit Manager](%MANAGER%) or your own custom tooling. 


### Integration



Gitblit has a pluggable user service mechanism which allows you to implement your own authentication, authorization, and user management.



Gitblit offers RSS feeds, a JSON-based RPC mechanism, and a [Java client API library](%API%) which allow you to integrate Gitblit into your systems.



### Backup Strategy



Gitblit includes a backup mechanism (*federation*) which can be used to backup repositories and, optionally, user accounts & server settings from your Gitblit instance to another Gitblit instance or to a [Gitblit Federation Client](%FEDCLIENT%).  Similarly you can use the federation mechanism to aggregate individual workspace Gitblit instances to a common, centralized server.





## Standard Features (GO/WAR)

- JGit SmartHTTP servlet

- Browser and git client authentication

- Four *per-repository* access control configurations with a Read-Only control flag


 docs/02_rpc.mkd

@@ -5,6 +5,7 @@
Gitblit optionally allows a remote client to administer the Gitblit server.  This client could be a Java-based tool or perhaps a tool written in another language.



    web.enableRpcServlet=true

    web.enableRpcManagement=false

    web.enableRpcAdministration=false



**https** is strongly recommended because passwords are insecurely transmitted form your browser/rpc client using Basic authentication!

@@ -15,14 +16,14 @@


[Gitblit Manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%) is an example Java/Swing application that allows remote management (repository and user objects) and administration (server settings) of a Gitblit server.

  

This application uses a combination of RSS feeds and the JSON RPC interface, both of which are part of the [Gitblit API](http://code.google.com/p/gitblit/downloads/detail?name=%API%) library.  Some JSON RPC methods from the utility class `com.gitblit.utils.RpcUtils` are not currently used by the Gitblit Manager.

This application uses a combination of RSS feeds and the JSON RPC interface, both of which are part of the [Gitblit API](http://code.google.com/p/gitblit/downloads/detail?name=%API%) library, to present live information from a Gitblit server.  Some JSON RPC methods from the utility class `com.gitblit.utils.RpcUtils` are not currently used by the Gitblit Manager.



**NOTE:**  

Gitblit Manager stores your login credentials **INSECURELY** in homedir/.gitblit/config.



### EGit "Import from Gitblit" Feature (Planning)

### Eclipse/EGit "Import from Gitblit" Feature (Planning)



One obvious goal of a Gitblit RPC mechanism would be to have an EGit Feature that allows authentication and enumeration of Gitblit repositories from the Eclipse *Import...* menu.  Cloning (hopefully batch) would be delegated to EGit.

One obvious goal of a Gitblit RPC mechanism would be to have an Eclipse/EGit Feature that allows authentication and enumeration of Gitblit repositories from the Eclipse *Import...* menu.  Batch cloning would be supported and delegated to EGit.



This particular project should not be difficult as the only external dependency for `com.gitblit.utils.RpcUtils` is [google-gson](http://google-gson.googlecode.com) which is already a dependency of the EGit/GitHub Mylyn feature.




 docs/05_roadmap.mkd

@@ -19,6 +19,7 @@
    * optional automatic push to origin/remotes?

    * optional manual push to origin/remotes?

* Gitblit: Lucene integration with multi-repository search (issue 16)

* Gitblit: Repository regex substitutions should be stored in .git/.config, not gitblit.properties



### TODO (low priority)