AsciiDoctor Git includes extension

An AsciiDoctor extension that enables file includes from Git repositories. It only affects include directives for URIs beginning with git@.

The extension can be used to include code examples from specific revisions in a git repository.

Requirements

git command is available in PATH.

Installation

With Ruby Gems:

gem install asciidoctor-git-include

Usage

Command line

Load the extension:

asciidoctor -r asciidoctor-git-include [index.adoc]

Then, inside your AsciiDoc file, use an include statement like normal, pointing to an URI that begins with git@.

Supported attributes

• repository - path to the Git repository (default: .)

• revision - repository revision to use (default: HEAD)

• lines - specify the lines to include (i.e. lines=2..5;10;12)

• diff - include a patch for the given revision, or between two revisions (see examples)

• difftarget - tell what the path of the target was before the changes (in case the target file was renamed)

• ignorewhitespaces - whether to ignore whitespaces and newlines changes in an included patch

Examples

Examples with actual rendered output can be found on https://jakzal.github.io/asciidoctor-git-include/. The source is taken from examples/index.adoc.

Basic

Save this one-line Asciidoc file as README.adoc:

include::[email protected][]

Then run

asciidoctor -r asciidoctor-git-include README.adoc

and open README.html in your browser.

Changing the repository and revision

include::[email protected][repository=/path/to/repository,revision=dbe7eb05972d24eb153495b543fe5ba0b362b0b1]

Changing the branch

include::[email protected][revision=develop]

Changing the path

Paths within the repository work as usual:

include::git@path/within/repo/file.rb[]

Specifying lines to include

include::[email protected][lines=2..5;10;12]

Including a patch for a specific revision

To generate a patch for changes introduced in a specific revision (b015e8dd):

include::git@path/within/repo/file.rb[revision=b015e8dd,diff]

Including a patch for specific revisions

To generate a patch for changes between two revisions (b015e8dd and b015e8dd):

include::git@path/within/repo/file.rb[revision=b015e8dd,diff=0245ac72]

Including a patch of a file that has been renamed

To generate a patch for changes between two revisions (b015e8dd and b015e8dd) where a file has been renamed:

include::git@path/within/repo/file.rb[revision=b015e8dd,diff=0245ac72,difftarget=path/within/repo/previous_file.rb]

Including a patch ignoring whitespaces

To generate a patch for changes introduced in a specific revision (b015e8dd) but ignoring the changes related to whitespaces and caret line return:

include::git@path/within/repo/file.rb[revision=b015e8dd,diff,ignorewhitespaces]