Git adapters

Gollum and gollum-lib use the Gollum::Git abstraction layer to perform Git object manipulation and reading git repositories. This allows us to separate the particular logic for accessing git repos on different platforms from gollum-lib's own API. Different adapters are provided that each instantiate the Gollum::Git API. These adapters are separate gems which are required automagically by gollum-lib, depending on your platform. See below for a description, or how to get started developing.

Rugged

The rugged adapter is currently the default on MRI ('regular' ruby). Rugged provides ruby bindings to libgit2.

RJGit (Java)

This adapter uses RJGit, a JRuby wrapper library for JGit. With this adapter, it is possible to run gollum on JRuby (and so also, e.g., on Windows). This is not possible with the default rugged adapter, because that uses Ruby C-extensions (which is problematic on JRuby). This adapter is the default when using JRuby, so no further steps are necessary to get it running after doing gem install gollum.

DEPRECATED: Grit

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 (https://gitlab.com/gitlab-org/gitlab-grit/tree/master). Still, gollum's use of grit has several disadvantages:

• grit's dependency on Posix:Spawn prohibits it to run on Windows or with JRuby
• grit was unable to handle utf-8 in filenames and contents
• grit was unable to handle filenames containing spaces

To remedy that, we decided to move away from grit. The first step in that process was to introduce a Gollum::Git abstraction layer and an adapter pattern. We have meanwhile finished two different adapters which do not share the above limitations. The grit adapter is therefore not being developed any longer, and its latest version is not compatible with gollum 5.x.

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}"}
```#