build.xml | ●●●●● patch | view | raw | blame | history | |
src/site/plugins_extensions.mkd | ●●●●● patch | view | raw | blame | history | |
src/site/plugins_overview.mkd | ●●●●● patch | view | raw | blame | history | |
src/site/setup_plugins.mkd | ●●●●● patch | view | raw | blame | history |
build.xml
@@ -576,7 +576,8 @@ </menu> <divider /> <menu name="Plugins" pager="true" pagerPlacement="bottom" pagerLayout="justified"> <page name="plugins" src="setup_plugins.mkd" /> <page name="overview" src="plugins_overview.mkd" /> <page name="extension points" src="plugins_extensions.mkd" /> </menu> <divider /> <page name="federation" src="federation.mkd" /> @@ -899,7 +900,8 @@ </menu> <divider /> <menu name="Plugins" pager="true" pagerPlacement="bottom" pagerLayout="justified"> <page name="plugins" src="setup_plugins.mkd" /> <page name="overview" src="plugins_overview.mkd" /> <page name="extension points" src="plugins_extensions.mkd" /> </menu> <divider /> <page name="federation" src="federation.mkd" /> src/site/plugins_extensions.mkd
New file @@ -0,0 +1,115 @@ ## Extension Points Gitblit offers several extension points for enhancing and customizing it's runtime behavior. Each available extension point has a sample implementation in the [gitblit-cookbook-plugin (Maven project)](https://dev.gitblit.com/summary/gitblit-cookbook-plugin.git). ### SSH Dispatch Command *SINCE 1.5.0* You can provide your own custom SSH commands by subclassing the *DispatchCommand* class. ```java import ro.fortsoft.pf4j.Extension; import com.gitblit.models.UserModel; import com.gitblit.transport.ssh.commands.CommandMetaData; import com.gitblit.transport.ssh.commands.DispatchCommand; @Extension @CommandMetaData(name = "mycommands", description = "Sample SSH dispatcher") public class MyDispatcher extends DispatchCommand { @Override protected void setup(UserModel user) { // commands in this dispatcher register(user, CommandA.class); register(user, CommandB.class); // nested dispatchers register(user, SubDispatcher1.class); register(user, SubDispatcher2.class); } } ``` ### Pre- and Post- Receive Hook *SINCE 1.5.0* You can provide your own custom pre and/or post receive hooks by subclassing the *ReceiveHook* class. ```java import com.gitblit.extensions.ReceiveHook; import java.util.Collection; import org.eclipse.jgit.transport.ReceiveCommand; import ro.fortsoft.pf4j.Extension; @Extension public class MyReceiveHook extends ReceiveHook { @Override public void onPreReceive(GitblitReceivePack receivePack, Collection<ReceiveCommand> commands) { } @Override public void onPostReceive(GitblitReceivePack receivePack, Collection<ReceiveCommand> commands) { } } ``` ### Patchset Hook *SINCE 1.5.0* You can provide your own custom patchset hook by subclassing the *PatchsetHook* class. ```java import com.gitblit.extensions.PatchsetHook; import com.gitblit.models.TicketModel; import ro.fortsoft.pf4j.Extension; @Extension public class MyPatchsetHook extends PatchsetHook { @Override public void onNewPatchset(TicketModel ticket) { } @Override public void onUpdatePatchset(TicketModel ticket) { } @Override public void onMergePatchset(TicketModel ticket) { } } ``` ### Ticket Hook *SINCE 1.5.0* You can provide your own custom ticket hook by subclassing the *TicketHook* class. ```java import com.gitblit.extensions.TicketHook; import com.gitblit.models.TicketModel; import com.gitblit.models.TicketModel.Change; import ro.fortsoft.pf4j.Extension; @Extension public class MyTicketHook extends TicketHook { @Override public void onNewTicket(TicketModel ticket) { } @Override public void onUpdateTicket(TicketModel ticket, Change change) { } } ``` src/site/plugins_overview.mkd
New file @@ -0,0 +1,73 @@ ## Gitblit Plugins *SINCE 1.5.0* Gitblit supports extending and enhancing the core functionality through plugins. This mechanism is very young and incomplete with few extension points, but you can expect it to evolve rapidly in upcoming releases. ### What is a plugin? A plugin is a collection of Java classes and required jar dependencies bundled together in a zip file. A plugin may optionally include *Extensions* which enhance Gitblit at specific Gitblit-specified *ExtensionPoints*. *Plugins* are singleton instances that are *STARTED* when Gitblit launches and *STOPPED* when Gitblit terminates. *Extensions* are dynamic instances that are created when Gitblit processes requests that trigger *ExtensionPoints*. ### Architecture The existing plugin mechanism is based on [pf4j](https://github.com/decebals/pf4j). Plugins are distributed as zip files and may include their runtime dependencies or may rely on the bundled dependencies of other plugins and/or Gitblit core. The zip plugins are stored in `${baseFolder}/plugins` and are unpacked on startup into folders of the same name. A plugin defines it's metadata in the META-INF/MANIFEST.MF file: Plugin-Id: powertools Plugin-Description: Gitblit Powertools Plugin-Class: com.gitblit.plugin.powertools.Powertools Plugin-Version: 1.2.0 Plugin-Provider: gitblit.com In addition to extending Gitblit core, plugins can also define extension points that may be implemented by other plugins. Therefore a plugin may depend on other plugins. Plugin-Dependencies: foo, bar **NOTE:** The pf4j plugin framework relies on a javac apt processor to generate compile-time extension information, so be sure to enable apt processing in your build process. #### Limitations of Dependencies & Requires Plugins may specify dependencies by ID, but may not specify specific versions of a dependency. The plugin registry allows you to specify a *requires* version of Gitblit, but this is not currently enforced. ### Managing Plugins Administrators may manage plugins through the `plugin` SSH dispatch command: ssh host plugin Through this command interface plugins can be started, stopped, disabled, enabled, installed, uninstalled, listed, etc. ### Default Plugin Registry Gitblit provides a simple default registry of plugins. The registry is a JSON file and it lists plugin metadata and download locations. plugins.registry = http://plugins.gitblit.com/plugins.json The [registry](http://plugins.gitblit.com/plugins.json) is currently hosted in a [Git repository on Github](https://github.com/gitblit/gitblit-registry). This git repository is also a [Maven-compatible repository](http://plugins.gitblit.com), which hosts some plugin binaries. ### Contributing Plugins to the Default Registry If you develop your own plugins that you want hosted by or linked in the default registry, open pull request for the registry repository. Any contributed binaries hosted in this repository must have Maven metadata and the SHA-1 & MD5 checksums. By default, Gitblit enforces checksum validation on all downloads. ### Hosting your Own Registry / Allowing Multiple Registries The `plugins.json` file is parameterized with the `${self}` placeholder. This parameter is substituted on download with with the source URL of the registry file. This allows you to clone and serve your own copy of this git repository or just server your own `plugins.json` on your own network. Gitblit also supports loading multiple plugin registries. Just place another **properly formatted** `.json` file in `${baseFolder}/plugins` and Gitblit will load that as an additional registry. ### Mac OSX Fonts Gitblit's core SSH commands and those in the *powertools* plugin rely on ANSI border characters to provide a pretty presentation of data. Unfortunately, the fonts provided by Apple - while very nice - don't work well with ANSI border characters. The following public domain fixed-width, fixed-point, bitmapped fonts work very nicely. I find the 6x12 font with a line spacing of ~0.8 to be quite acceptable. [6x12.dfont](6x12.dfont) [6x13.dfont](6x13.dfont) [7x13.dfont](7x13.dfont) [7x14.dfont](7x14.dfont) src/site/setup_plugins.mkd
File was deleted