mirror of
https://github.com/foo-dogsquared/asciidoctor-foodogsquared-extensions.git
synced 2025-01-31 16:57:56 +00:00
59 lines
2.3 KiB
Plaintext
59 lines
2.3 KiB
Plaintext
= Git blob include processor
|
|
:toc:
|
|
|
|
|
|
An include processor that includes content from the current Git repo.
|
|
The use case for this is specifically for creating dedicated branches for certain content.
|
|
|
|
|
|
== Synopsis
|
|
|
|
[source, asciidoc]
|
|
----
|
|
include::git:$REVSPEC[]
|
|
----
|
|
|
|
Where `$REVSPEC` is a revision as specified in link:https://manpages.debian.org/gitrevisions.7[gitrevisions.7].
|
|
Take note this include processor only accepts a blob object's content to be extracted.
|
|
This is meant to be used with other attributes.
|
|
See <<Attributes>> for more details.
|
|
|
|
If the resulting operation ends in an error (i.e., non-existing revision, file, something went wrong), it should log a warning and transclude an error.
|
|
|
|
|
|
== Attributes
|
|
|
|
- `path` is the filepath to be retrieved from the revision.
|
|
|
|
- `context-lines` is the number of surrounding lines for the diff.
|
|
This is only effective if `diff` option is given.
|
|
|
|
There's also a couple of link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options] for this component.
|
|
You can give the following options through `opts` attribute (i.e., `opts="diff,reverse"`).
|
|
|
|
- `diff` will show the difference in link:https://en.wikipedia.org/wiki/Diff[diff] format.
|
|
|
|
- `reverse` reverses the sides to be compared.
|
|
|
|
|
|
== Extra notes
|
|
|
|
The extension is composed of two parts: an include processor and a preprocessor.
|
|
|
|
The preprocessor add a document attribute, `doccontentref`, which it gives the Git reference for that content.
|
|
`doccontentref` is the difference between the process working directory (`Dir.pwd`) and the base directory of the content to be converted.
|
|
In case the process working directory is not entirely consistent for several reasons, you could give the attribute `rootdir` as the basis for the comparison.
|
|
|
|
The include processor also accepts an empty target with the prefix (i.e., `include::git:[]`) as a shorthand for `include::git:{doccontentref}`.
|
|
|
|
|
|
== Example usage
|
|
|
|
The following examples assume that `doccontentref` points to `content/posts/sample`.
|
|
|
|
- `include::git:HEAD[path=shell.nix]` should transclude the current iteration of `shell.nix`.
|
|
|
|
- `include::git:{doccontentref}[opts="diff", path=Gemfile]` should include a diff of the Gemfile from `content/posts/sample` branch (assuming that Gemfile has changed).
|
|
|
|
- `include::git:non-existing-rev[opts="diff"]` should result in a warning with the non-existing revision.
|