Git adapters

Budweiser edited this page Apr 27, 2016 · 13 revisions

For a long time, gollum relied on grit for manipulating git repositories. Unfortunately, the grit project was abandoned, which made us decide to switch to a grit fork maintained by the gitlab team. Still, gollum's use of grit has several disadvantages, most saliently the fact that grit's dependency on Posix:Spawn prohibits it to run on Windows or with JRuby. To remedy that, we have made an effort to start moving away from grit. And the first step in that process was to introduce a Gollum::Git abstraction layer and an adapter pattern. That way, it will be much easier in the future to change gollum's git backend.

Grit

At present, gollum uses the grit-adapter by default. This adapter uses gitlab-grit to manipulate git repositories.

Rugged

A rugged adapter is under development (contributors welcome!). Once this adapter is fully functional, the plan is to make it the default adapter instead of the grit-adapter. Until then, using this adapter is at your own risk.

RJGit (Java)

A third-party adapter is being developed that uses RJGit, a JRuby wrapper library for JGit. With this adapter, it is possible to run gollum on JRuby. The adapter passes all the tests for gollum and gollum-lib, but is new and therefore might well contain bugs. Please report them at the adapter's issue tracker!

This adapter is the default when using jruby, so no further steps are necessary to get it running after doing gem install gollum.

CHANGING ADAPTERS

Command line

  1. Make sure you install the target adapter first, e.g. [sudo] gem install gollum-rugged_adapter.
  2. When launching Gollum, use the --adapter command line option:
# replace "ADAPTER" for the target adapter, e.g. "rugged"
gollum --adapter [ADAPTER]

Rack configuration file

Put the following into your config.ru (before you require gollum):

module Gollum
  # to require 'my_adapter':
  Gollum::GIT_ADAPTER = "my"
end

HOW TO CONTRIBUTE

Existing adapters

  • Fork the gollum-lib repository
  • Fork the adapter you're interested in
  • Change gollum-lib's Gemfile to point to your local adapter (gem ADAPTER, :path => PATH)
  • Run bundle install
  • Write a test case
  • Write your code
  • Run the adapter's test suite
  • Run gollum-libs test suite
  • If everything passes, open a pull request

Creating your own

There are generic adapter specs for the gollum project. If you're starting a new adapter project, be sure to begin by making these specs pass. To include them, add the following line to the project's Gemfile:

gem 'adapter_specs', :git => 'https://github.com/gollum/adapter_specs.git'

Then in spec/spec_helper.rb add the following lines:

gem_spec = Gem::Specification.find_by_name('adapter_specs')
gem_spec_dir = "#{gem_spec.gem_dir}/#{gem_spec.require_paths[0]}"
Dir.glob("#{gem_spec_dir}/**/*.rb").each {|spec| require "#{spec}"}
```# 
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.