Examples for AsciiDoctor Git includes extension

Including a file from git

Here’s how to include the code from the first commit (revision fdc094c892b) to lib/asciidoctor-git-include.rb:

.lib/asciidoctor-git-include.rb
[source,ruby]
----
include::git@lib/asciidoctor-git-include.rb[revision=fdc094c892b,lines=5;11..24]
----

The above code, when embedded in an asciidoc, will render selected lines from the file in the specified revision:

lib/asciidoctor-git-include.rb

class GitIncludeMacro < Asciidoctor::Extensions::IncludeProcessor

  def process doc, reader, target, attributes
    target.slice! "git@"
    repository = attributes.fetch('repository', '.')
    revision = attributes.fetch('revision', 'HEAD')

    cmd = %(git -C #{repository} show #{revision}:#{target})
    content = %x(#{cmd})

    reader.push_include content, target, target, 1, attributes
    reader
  end
end

The revision is optional (HEAD is the default) as well as the lines.

Including a diff from git

Include the diff from the second commit (revision d64d85e37b4) to its preceding revision of lib/asciidoctor-git-include.rb:

.Changes introduced in d64d85e37b4
[source,patch]
----
include::git@lib/asciidoctor-git-include.rb[revision=d64d85e37b4,diff,lines=7..17]
----

The above code will render:

Changes introduced in d64d85e37b4

     repository = attributes.fetch('repository', '.')
     revision = attributes.fetch('revision', 'HEAD')
+    lines = attributes.fetch('lines', '')
 
     cmd = %(git -C #{repository} show #{revision}:#{target})
     content = %x(#{cmd})
 
+    content = process_line_selection(content, lines) unless lines == ""
+
     reader.push_include content, target, target, 1, attributes
     reader

Including a diff between any two revisions

Include the diff between two revisions (e3b17ded3 and d64d85e37b4) of lib/asciidoctor-git-include.rb:

.Changes between e3b17ded3 and d64d85e37b4
[source,patch]
----
include::git@lib/asciidoctor-git-include.rb[revision=e3b17ded3,diff=d64d85e37b4,lines=6..18]
----

The above code will render:

Changes between e3b17ded3 and d64d85e37b4

     repository = attributes.fetch('repository', '.')
     revision = attributes.fetch('revision', 'HEAD')
     lines = attributes.fetch('lines', '')
+    as_diff = attributes.value?('diff') || attributes.key?('diff')
+    diff_revision = attributes.fetch('diff', "#{revision}~1")
 
     cmd = %(git -C #{repository} show #{revision}:#{target})
+    if (as_diff)
+      cmd = %(git -C #{repository} diff #{diff_revision}:#{target} #{revision}:#{target})
+    end
     content = %x(#{cmd})
 
     content = process_line_selection(content, lines) unless lines == ""

Including code or diff from a different repository

The repository attribute can be given to point to an external repository location.

.lib/asciidoctor-git-include.rb
[source,ruby]
----
include::git@lib/asciidoctor-git-include.rb[revision=fdc094c892b,lines=5;24,repository=.]
----

The above code will render:

lib/asciidoctor-git-include.rb

class GitIncludeMacro < Asciidoctor::Extensions::IncludeProcessor
end

The example uses the current repository location for practical reasons, but any local filesystem location should work.

Building this page

Clone the repository.

git clone https://github.com/jakzal/asciidoctor-git-include.git
cd asciidoctor-git-include

Next, choose whether you’d like to use Docker or build the gem directly on your OS. Continue with one of the sections that follow.

Docker

Build the Docker image with the asciidoctor-git-include extension. The docker build command should be run at the top level directory of this project.
Building the Docker image
```
docker build -t jakzal/asciidoctor .
```

Build the page.

Building the page with Docker

docker run -t --rm --name docs -v $(pwd):/project -w /project jakzal/asciidoctor \
    asciidoctor -r asciidoctor-git-include examples/index.adoc -o examples/index.html

Open the generated examples/index.html in a browser.

Gem

Install asciidoctor on your system.
```
gem install asciidoctor rouge
```
Build the extension gem and install it on your system.
Building and installing the gem
```
gem build asciidoctor-git-include.gemspec
gem install asciidoctor-git-include-*.gem
```
This will the development version. To install the version published to ruby gems run the following command instead:
```
gem install asciidoctor-git-include
```

Build the page

Building the page with asciidoctor

asciidoctor -r asciidoctor-git-include examples/index.adoc -o examples/index.html

Open the generated examples/index.html in a browser.