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.

With Ruby Gems:

gem install asciidoctor-git-include

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@.

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)

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

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

include::git@README.adoc[]

Then run

asciidoctor -r asciidoctor-git-include README.adoc

and open README.html in your browser.

include::git@README.adoc[repository=/path/to/repository,revision=dbe7eb05972d24eb153495b543fe5ba0b362b0b1]

include::git@README.adoc[revision=develop]

Paths within the repository work as usual:

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

include::git@README.adoc[lines=2..5;10;12]

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

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

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

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