https://github.com/jakzal/asciidoctor-git-include
AsciiDoctor extension that enables file includes from Git repositories
https://github.com/jakzal/asciidoctor-git-include
asciidoctor asciidoctor-extension diff git include
Last synced: 4 months ago
JSON representation
AsciiDoctor extension that enables file includes from Git repositories
- Host: GitHub
- URL: https://github.com/jakzal/asciidoctor-git-include
- Owner: jakzal
- License: mit
- Created: 2023-05-30T14:34:53.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-11T13:45:07.000Z (over 1 year ago)
- Last Synced: 2025-11-29T22:42:35.814Z (6 months ago)
- Topics: asciidoctor, asciidoctor-extension, diff, git, include
- Language: Ruby
- Homepage: https://jakzal.github.io/asciidoctor-git-include/
- Size: 95.7 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
= AsciiDoctor Git includes extension
ifndef::env-github[:icons: font]
ifdef::env-github[]
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
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
// tag::examples[]
== Examples
Examples with actual rendered output can be found on https://jakzal.github.io/asciidoctor-git-include/.
The source is taken from xref:examples/index.adoc[].
=== Basic
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.
=== Changing the repository and revision
----
\include::git@README.adoc[repository=/path/to/repository,revision=dbe7eb05972d24eb153495b543fe5ba0b362b0b1]
----
=== Changing the branch
----
\include::git@README.adoc[revision=develop]
----
=== Changing the path
Paths within the repository work as usual:
----
\include::git@path/within/repo/file.rb[]
----
=== Specifying lines to include
----
\include::git@README.adoc[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]
----
// end::examples[]