How To's

CLI Flag ‘false’ value

Boolean flags can only take arguments via --flag=[true|false] or for short names (if available) -f=[true|false]. You cannot use --flag [true|false] nor can you use the shorthand -f [true|false] as it will result in the following error:

Error: accepts 1 arg(s), received 2

Configuration File

Since v0.10.0

Configuration can be loaded with -c, --config string. Take a look at configuration page for all the details.

As of v0.13.0, --config flag accepts both relative and absolute paths.

$ pwd
/path/to/parent/folder

$ tree
.
├── module-a
│   └── main.tf
├── module-b
│   └── main.tf
├── ...
└── .terraform-docs.yml

# executing from parent
$ terraform-docs -c .terraform-docs.yml module-a/

# executing from child
$ cd module-a/
$ terraform-docs -c ../.terraform-docs.yml .

# or an absolute path
$ terraform-docs -c /path/to/parent/folder/.terraform-docs.yml .

Visibility of Sections

Since v0.10.0

Output generated by terraform-docs consists of different sections which are visible by default. The visibility of these can be controlled by one of the following options:

  • --show <name>
  • --hide <name>
  • --show-all (deprecated in v0.13.0, removed in v0.15.0)
  • --hide-all (deprecated in v0.13.0, removed in v0.15.0)

As of v0.13.0 flags --show-all and --hide-all are deprecated in favor of explicit use of --show and --hide. In other words when --show <section> is used, only <section> will be shown. If you want to show multiple sections and hide the rest you can specify --show flag multiple times. The same logic is also applied to --hide.

# show 'inputs' and hide everything else
$ terraform-docs --show inputs <formatter>

# show 'inputs' and show 'outputs' and hide everything else
$ terraform-docs --show inputs --show outputs <formatter>

# hide 'header' and show everything else
$ terraform-docs --hide header <formatter>

# hide 'header' and hide 'providers' and show everything else
$ terraform-docs --hide header --hide providers <formatter>

Note: Using --show or --hide CLI flag will completely override the values from .terraform-docs.yml.

$ cat .terraform-docs.yml
sections:
  show:
    - inputs
    - outputs

# example 1: this will only show 'providers'
$ terraform-docs --show providers .

# example 2: this will hide 'inputs' and hide 'providers' and show everything else
$ terraform-docs --hide inputs --hide providers .

Module Header

Since v0.10.0

Module header can be extracted from different sources. Default file to extract header from is main.tf, otherwise you can specify the file with --header-from FILE or corresponding header-from in configuration file. Supported file formats to read header from are:

  • .adoc
  • .md
  • .tf
  • .txt

The whole file content is being extracted as module header when extracting from .adoc, .md, or .txt. But to extract header from .tf file you need to use following javascript, c or java like multi-line comment:

/**
 * # Main title
 *
 * Everything in this comment block will get extracted.
 *
 * You can put simple text or complete Markdown content
 * here. Subsequently if you want to render AsciiDoc format
 * you can put AsciiDoc compatible content in this comment
 * block.
 */

resource "foo" "bar" { ... }

Note: This comment must start at the immediate first line of the .tf file before any resource, variable, module, etc.

Note: we will never alter line-endings of extracted header text and will assume whatever extracted is intended as is. It’s up to you to apply any kind of Markdown formatting to them (i.e. adding <SPACE><SPACE> at the end of lines for break, etc.)

Since v0.12.0

Extracting module footer works exactly like header with one exception. There is no default file to attempt extraction from, you need to explicitly specify desired file to extract content from with --footer-from FILE or corresponding footer-from in configuration file.

Include Examples

Since v0.14.0

Example can be automatically included into README by using content in configuration file. There are [multiple variables and function] available in content. As an example:

$ tree
.
├── examples
│   ├── example-1
│   │   ├── main.tf
│   └── example-2
│       └── main.tf
├── ...
├── main.tf
├── variables.tf
├── ...
└── .terraform-docs.yml

and

# .terraform-docs.yml
content: |-
  {{ .Header }}

  ## Example

  ```hcl
  {{ include "examples/example-1/main.tf" }}
  ```

  {{ .Inputs }}

  {{ .Outputs }}  

Insert Output To File

Since v0.12.0

Generated output can be insterted directly into the file. There are two modes of insersion: inject (default) or replace. Take a look at output configuration for all the details.

terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module

Note that --output-file can be relative to module path or an absolute path in filesystem.

$ pwd
/path/to/module

$ tree .
.
├── docs
│   └── README.md
├── ...
└── main.tf

# this works, relative path
$ terraform-docs markdown table --output-file ./docs/README.md .

# so does this, absolute path
$ terraform-docs markdown table --output-file /path/to/module/docs/README.md .

Generate terraform.tfvars

Since v0.9.0

You can generate terraform.tfvars in both hcl and json format by executing the following, respectively:

terraform-docs tfvars hcl /path/to/module

terraform-docs tfvars json /path/to/module

Note: Required input variables will be "" (empty) in HCL and null in JSON format.

GitHub Action

To use terraform-docs GitHub Action, configure a YAML workflow file (e.g. .github/workflows/documentation.yml) with the following:

name: Generate terraform docs
on:
  - pull_request

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        ref: ${{ github.event.pull_request.head.ref }}

    - name: Render terraform docs and push changes back to PR
      uses: terraform-docs/gh-actions@v0.6.0
      with:
        working-dir: .
        output-file: USAGE.md
        output-method: inject
        git-push: "true"

Read more about terraform-docs GitHub Action and its configuration and examples.

Pre-commit Hook

Since v0.12.0

With pre-commit, you can ensure your Terraform module documentation is kept up-to-date each time you make a commit.

First, simply create or update a .pre-commit-config.yaml in the root of your Git repo with at least the following content:

repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: "<VERSION, TAG, OR SHA TO USE>"             # e.g. "v0.11.2"
    hooks:
      - id: terraform-docs-go
        args: ["ARGS", "TO PASS", "INCLUDING PATH"]  # e.g. ["--output-file", "README.md", "./mymodule/path"]

(You can also include more than one entry under hooks: to update multiple docs. Just be sure to adjust the args: to pass the path you want terraform-docs to scan.)

Second, install pre-commit and run pre-commit to activate the hooks.

Then, make a Terraform change, git add and git commit! Pre-commit will regenerate your Terraform docs, after which you can rerun git add and git commit to commit the code and doc changes together.

You can also regenerate the docs manually by running pre-commit -a terraform-docs.

Pre-commit via Docker

The pre-commit hook can also be run via Docker, for those who don’t have Go installed. Just use id: terraform-docs-docker in the previous example.

This will build the Docker image from the repo, which can be quite slow. To download the pre-built image instead, change your .pre-commit-config.yaml to:

repos:
  - repo: local
    hooks:
      - id: terraform-docs
        name: terraform-docs
        language: docker_image
        entry: quay.io/terraform-docs/terraform-docs:latest  # or, change latest to pin to a specific version
        args: ["ARGS", "TO PASS", "INCLUDING PATH"]          # e.g. ["--output-file", "README.md", "./mymodule/path"]
        pass_filenames: false

Git Hook

A simple git hook (.git/hooks/pre-commit) added to your local terraform repository can keep your Terraform module documentation up to date whenever you make a commit. See also git hooks documentation.

#!/bin/sh

# Keep module docs up to date
for d in modules/*; do
  if terraform-docs md "$d" > "$d/README.md"; then
    git add "./$d/README.md"
  fi
done

Note: This is very basic and higly simplified version of pre-commit-terraform. Please refer to it for complete examples and guides.

Edit on GitHub