adr-log

adr-log

Generate an architectural decision log out of architectural decision records (ADRs).

Table of Contents

• Install
• CLI
• Usage
  • Examples
    • Printing the adr log to stdout
    • Generating an index.md file containing the adr log
• Developing
• Related Tooling
• License

Install

Install with npm:

npm install -g adr-log

CLI

Usage: adr-log [-d <directory>] [-i] <input>

  input:  The markdown file to contain the table of contents.
          If no <input> file is specified, an index.md file containing the log is created in the current directory.

  -i:     Edit the <input> file directly, injecting the log at <!-- adrlog -->.
          Using only the -i flag, the tool will scan the current working directory for all *.md files and
          inject the resulting adr-log into the default index.md file.
          (Without this flag, the default is to print the log to stdout.)

  -d:     Scans the given <directory> for .md files.
          (Without this flag, the current working directory is chosen as default.)

  -h:     Shows how to use this program

Usage

Examples

Printing the adr log to stdout

Consider a directory consisting of three files (0000-example-1.md, 0001-example-2.md, 0002-example-3.md). Execute following command:

adr-log -d .

This outputs following log on your console:

* [ADR-0000](0000-example-1.md) - Example 1
* [ADR-0001](0001-example-2.md) - Example 2
* [ADR-0002](0002-example-3.md) - Example 3

Generating an index.md file containing the adr log

Since this is basically a fork of Jon Schlinkert's markdown-toc, you can also choose to insert the log into an existing file. For this to work the file must contain an opening <!-- adrlog --> code comment, after which the log will be inserted.

If the file already contains an adrlog surrounded by an opening <!-- adrlog --> and closing <!-- adrlogstop --> code comment, the existing is be replaced.

Using -i alone (adr-log -i) generates an index.md file in the current working directory containing the log.

$ adr-log -i

Result in following index.md:

<!-- adrlog -->

* [ADR-0000](0000-example-1.md) - Example 1
* [ADR-0001](0001-example-2.md) - Example 2
* [ADR-0002](0002-example-3.md) - Example 3

<!-- adrlogstop -->

Alternative Indexing

• search recursively underneath the given directory
• allow date prefixes as well as number prefixes
• allow specification of index or date properties in frontmatter
• fallback to auto-numbering for ADRs without filename prefixes or frontmatter

Developing

• Run node cli.js to execute the CLI. Also works with relative directgories. E.g., node ../../../adr-log/cli.js -d . runs adr-log and outputs the result to the console.
• You can turn on debugging output by adjusting lines 6 and 7 in cli.js.
• Use relase-it and github-release-from-changelog for release management. See also ADR-0003.

Related Tooling

adr-tools is the most prominent related tool. It supports generating an ADR log by using adr generate toc. An example to can be investigated at https://github.com/npryce/adr-tools/blob/master/tests/generate-contents.expected.

The difference to adr-tools is

1. adr-log is available using npm and thus more easy to install.
2. adr-tools does not include the heading of each ADR into the output.

License

Copyright © 2017 Tino Stadelmaier, Oliver Kopp, Armin Hüneburg, Tobias Wältken.

Released under the MIT License.

Changelog

[2.2.0] – 2020-10-22

Added

• New option -p - prefix for each ADR file path in log (useful when ADRs are in sub sub directory)
• New option -e option to specify glob pattern for files to be excluded
• Allow date prefixes as well as number prefixes
• Allow specification of index or date properties in frontmatter

Fixed

• Fixed bug where bogus path info is prepended to TOC entries when directory argument doesn't include trailing slash

Changed

• Lists are now generated using * instead of -
• Search recursively underneath the given directory