From fa5e6f97aab0faca8e11ab8a264b0190c145b07f Mon Sep 17 00:00:00 2001 From: James Moger Date: Fri, 4 Nov 2011 17:25:00 -0400 Subject: [PATCH] Documentation. --- docs/00_index.mkd | 8 +++--- docs/01_features.mkd | 2 +- docs/02_rpc.mkd | 66 ++++++++++++++++++++++++++++++-------------- docs/04_releases.mkd | 6 ++-- 4 files changed, 53 insertions(+), 29 deletions(-) diff --git a/docs/00_index.mkd b/docs/00_index.mkd index 9274ed17..7916fe69 100644 --- a/docs/00_index.mkd +++ b/docs/00_index.mkd @@ -18,7 +18,7 @@ Gitblit is available in two variations: ### Tools -- *Gitblit API* - a JSON RPC client library for integrating Gitblit into your systems +- *Gitblit API* - an RSS/JSON RPC client library for integrating Gitblit into your systems - *Gitblit Manager* - a Java/Swing application for remote administration of a Gitblit server which uses the Gitblit API library - *Gitblit Federation Client* - a command line tool to clone/pull groups of repositories and optionally users and settings @@ -39,7 +39,7 @@ Gitblit requires a Java 6 Runtime Environment (JRE) or a Java 6 Development Kit **New:** *web.enableRpcServlet = true* **New:** *web.enableRpcManagement = false* **New:** *web.enableRpcAdministration = false* -- added: Gitblit API JSON RPC library +- added: Gitblit API RSS/JSON RPC library - added: Gitblit Manager (Java/Swing Application) for remote administration of a Gitblit server. - added: per-repository setting to skip size calculation (faster repositories page loading) - added: per-repository setting to skip summary metrics calculation (faster summary page loading) @@ -54,10 +54,10 @@ Gitblit requires a Java 6 Runtime Environment (JRE) or a Java 6 Development Kit - fixed: Gitblit now runs on Servlet 3.0 webservers (e.g. Tomcat 7, Jetty 8) (issue 23) - fixed: Set the RSS content type of syndication feeds for Firefox 4 (issue 22) - fixed: RSS feeds are now properly encoded to UTF-8 -- fixed: RSS feeds now properly generated parameterized links if *web.mountParameters=false* +- fixed: RSS feeds now properly generate parameterized links if *web.mountParameters=false* - 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 -- updated: MarkdownPapers 1.2.4 +- updated: MarkdownPapers 1.2.5 issues, binaries, and sources @ [Google Code][googlecode]
sources @ [Github][gitbltsrc] diff --git a/docs/01_features.mkd b/docs/01_features.mkd index 5f15aaea..cd4fecf1 100644 --- a/docs/01_features.mkd +++ b/docs/01_features.mkd @@ -8,7 +8,7 @@ - ![view](shield_16x16.png) *Authenticated View, Clone & Push* - ![freeze](cold_16x16.png) Freeze repository (i.e. deny push, make read-only) - Ability to federate with one or more other Gitblit instances -- JSON RPC interface +- RSS/JSON RPC interface - Java/Swing Gitblit Manager tool - Gitweb inspired web UI - Administrators may create, edit, rename, or delete repositories through the web UI or RPC interface diff --git a/docs/02_rpc.mkd b/docs/02_rpc.mkd index f238314c..bb58d68f 100644 --- a/docs/02_rpc.mkd +++ b/docs/02_rpc.mkd @@ -1,4 +1,4 @@ -## JSON Remote Procedure Call (RPC) Interface +## Remote Management, Administration and Integration *SINCE 0.7.0* @@ -9,9 +9,51 @@ Gitblit optionally allows a remote client to administer the Gitblit server. Thi **https** is strongly recommended because passwords are insecurely transmitted form your browser/rpc client using Basic authentication! -The Gitblit RPC mechanism, like the Gitblit JGit servlet, syndication/feed servlet, etc, supports request-based authentication. Making an *admin* request will trigger Gitblit's basic authentication mechanism. Listing of repositories, generally, will not trigger this authentication mechanism unless *web.authenticateViewPages=true*. That means its possible to allow anonymous enumeration of repositories that are not *view restricted* or *clone restricted*. Of course, if credentials are provided then all private repositories that are available to the user account will be enumerated in the JSON response. +The Gitblit JSON RPC mechanism, like the Gitblit JGit servlet, syndication/feed servlet, etc, supports request-based authentication. Making an *admin* request will trigger Gitblit's basic authentication mechanism. Listing of repositories, generally, will not trigger this authentication mechanism unless *web.authenticateViewPages=true*. That means its possible to allow anonymous enumeration of repositories that are not *view restricted* or *clone restricted*. Of course, if credentials are provided then all private repositories that are available to the user account will be enumerated in the JSON response. + +### Gitblit Manager + +[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. + +**NOTE:** +Gitblit Manager stores your login credentials **INSECURELY** in homedir/.gitblit/config. + +### 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. + +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. + +One proposal from the EGit team is to define a common JSON RPC method for enumeration of repositories which can be implemented by Git hosts. The EGit team would then implement the UI and the client-side enumeration code. This idea was raised as part of this [feature request for EGit](https://bugs.eclipse.org/bugs/show_bug.cgi?id=361251). + +Currently this project is in the planning stage. + +## RSS Query Interface + +At present, Gitblit does not yet support retrieving Git objects (commits, etc) via the JSON RPC mechanism. However, the repository/branch RSS feeds can be used to extract log/history information from a repository branch. + +The Gitblit API includes methods for retrieving and interpreting RSS feeds. The Gitblit Manager uses these methods to allow branch activity monitoring and repository searching. + + + + + + + + + + +
url parameterdefaultdescription
standard query
repositoryrequiredrepository name is part of the url (see examples below)
h=optional
default: HEAD		starting branch, ref, or commit id
l=optional
default: web.syndicationEntries		maximum return count
search query
s=requiredsearch string
st=optional
default: COMMIT		search type
+ +### Example RSS Queries -### RPC Requests + https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master + https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=documentation + https://localhost:8443/feed/gitblit.git?l=50&h=refs/heads/master&s=james&st=author + +## JSON Remote Procedure Call (RPC) Interface @@ -52,24 +94,6 @@ The Gitblit RPC mechanism, like the Gitblit JGit servlet, syndication/feed servl
url parametersrequired
user
permission		json
501unknown requestGitblit does not recognize the RPC request type
-### Gitblit Manager - -[Gitblit Manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%) is an example Java/Swing application that allows remote administration of a Gitblit server. -This application exercises many, but not all, methods from the utility class `com.gitblit.utils.RpcUtils`. - -**NOTE:** -Gitblit Manager stores your login credentials **INSECURELY** in homedir/.gitblit/config. - -### 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. - -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. - -One proposal from the EGit team is to define a common JSON RPC method for enumeration of repositories which can be implemented by Git hosts. The EGit team would then implement the UI and the client-side enumeration code. This idea was raised as part of this [feature request for EGit](https://bugs.eclipse.org/bugs/show_bug.cgi?id=361251). - -Currently this project is in the planning stage. - ### Example: LIST_REPOSITORIES **url**: https://localhost/rpc?req=LIST_REPOSITORIES diff --git a/docs/04_releases.mkd b/docs/04_releases.mkd index d57c709a..1093fcdc 100644 --- a/docs/04_releases.mkd +++ b/docs/04_releases.mkd @@ -12,7 +12,7 @@ **New:** *web.enableRpcServlet = true* **New:** *web.enableRpcManagement = false* **New:** *web.enableRpcAdministration = false* -- added: Gitblit API JSON RPC library +- added: Gitblit API RSS/JSON RPC library - added: Gitblit Manager (Java/Swing Application) for remote administration of a Gitblit server. - added: per-repository setting to skip size calculation (faster repositories page loading) - added: per-repository setting to skip summary metrics calculation (faster summary page loading) @@ -27,10 +27,10 @@ - fixed: Gitblit now runs on Servlet 3.0 webservers (e.g. Tomcat 7, Jetty 8) (issue 23) - fixed: Set the RSS content type of syndication feeds for Firefox 4 (issue 22) - fixed: RSS feeds are now properly encoded to UTF-8 -- fixed: RSS feeds now properly generated parameterized links if *web.mountParameters=false* +- fixed: RSS feeds now properly generate parameterized links if *web.mountParameters=false* - 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 -- updated: MarkdownPapers 1.2.4 +- updated: MarkdownPapers 1.2.5 ### Older Releases -- 2.39.5