From faf9f6aedc207d77d7dd5d8ac5c05731d9510f3c Mon Sep 17 00:00:00 2001 From: Ronny Orot Date: Mon, 22 Jul 2024 18:35:59 +0300 Subject: [PATCH] Add documentation about the new .tofu extension (#1841) Signed-off-by: Ronny Orot --- website/docs/cli/commands/index.mdx | 5 ++-- website/docs/cli/commands/plan.mdx | 7 +++--- website/docs/cli/commands/test/index.mdx | 22 +++++++++++++--- website/docs/cli/config/config-file.mdx | 4 +-- .../docs/language/files/dependency-lock.mdx | 8 +++--- website/docs/language/files/index.mdx | 25 ++++++++++++++----- website/docs/language/files/override.mdx | 25 +++++++++++++------ .../docs/language/modules/develop/index.mdx | 6 ++--- website/docs/language/modules/index.mdx | 8 +++--- website/docs/language/modules/syntax.mdx | 4 +-- website/docs/language/syntax/json.mdx | 17 +++++++++++-- 11 files changed, 93 insertions(+), 38 deletions(-) diff --git a/website/docs/cli/commands/index.mdx b/website/docs/cli/commands/index.mdx index 79da4e1ce9..8b154c087e 100644 --- a/website/docs/cli/commands/index.mdx +++ b/website/docs/cli/commands/index.mdx @@ -65,8 +65,9 @@ command's page for details. ## Switching working directory with `-chdir` The usual way to run OpenTofu is to first switch to the directory containing -the `.tf` files for your root module (for example, using the `cd` command), so -that OpenTofu will find those files automatically without any extra arguments. +the `.tf` or `.tofu` files for your root module (for example, using the `cd` +command), so that OpenTofu will find those files automatically without any +extra arguments. In some cases though — particularly when wrapping OpenTofu in automation scripts — it can be convenient to run OpenTofu from a different directory than diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index b2ecd51572..a6eec71f5e 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -314,9 +314,10 @@ The available options are: OpenTofu will allow any filename for the plan file, but a typical convention is to name it `tfplan`. **Do not** name the file with a suffix - that OpenTofu recognizes as another file format; if you use a `.tf` suffix - then OpenTofu will try to interpret the file as a configuration source - file, which will then cause syntax errors for subsequent commands. + that OpenTofu recognizes as another file format; if you use a `.tf` or + `.tofu` suffix then OpenTofu will try to interpret the file as a + configuration source file, which will then cause syntax errors for subsequent + commands. The generated file is not in any standard format intended for consumption by other software, but the file _does_ contain your full configuration, diff --git a/website/docs/cli/commands/test/index.mdx b/website/docs/cli/commands/test/index.mdx index 5296378bcc..0c5f433022 100644 --- a/website/docs/cli/commands/test/index.mdx +++ b/website/docs/cli/commands/test/index.mdx @@ -44,8 +44,8 @@ the required conditions (assertions) are met. Once the test is complete, OpenTof Usage: `tofu test [options]`. -This command will execute all `*.tftest.hcl` files in the current directory or in a directory called `tests`. You can -customize this behavior using the [options](#options) below. +This command will execute all `*.tftest.hcl`, `*.tftest.json`, `*.tofutest.hcl`, and `*.tofutest.json` files in the +current directory or in a directory called `tests`. You can customize this behavior using the [options](#options) below. :::info Example @@ -67,6 +67,22 @@ below. ::: +## Extension Precedence +When both `.tftest.hcl` and `.tofutest.hcl` files with the same base name are present in a +directory, OpenTofu will prioritize the `.tofutest.hcl` file and ignore the `.tftest.hcl` file. +For example: + +- If both `main.tftest.hcl` and `main.tofutest.hcl` exist in the same directory, OpenTofu will +only load `main.tofutest.hcl` and ignore `main.tftest.hcl`. + +This ensures that `.tofu` files always take precedence over `.tf` files when +both are available. This scenario can be useful for module authors who want +their modules to support both OpenTofu and Terraform and want to create different tests for each. + +The same rule applies to JSON-based test files: +- if both `main.tftest.json` and `main.tofutest.json` exist in the same directory, OpenTofu will +only load `main.tofutest.json` and ignore `main.tftest.json`. + ## Options * `-test-directory=path` Set the test directory (default: "tests"). OpenTofu will search for test files in the specified @@ -124,7 +140,7 @@ times to run more than one test file. ::: -## The `*.tftest.hcl` file structure +## The `*.tftest.hcl` / `*.tofutest.hcl` file structure The testing language of OpenTofu is similar to the main OpenTofu language and uses the same block structure. diff --git a/website/docs/cli/config/config-file.mdx b/website/docs/cli/config/config-file.mdx index 0b8c00604a..3271915d04 100644 --- a/website/docs/cli/config/config-file.mdx +++ b/website/docs/cli/config/config-file.mdx @@ -43,8 +43,8 @@ Any such file should follow the naming pattern `*.tfrc`. ## Configuration File Syntax -The configuration file uses the same _HCL_ syntax as `.tf` files, but with -different attributes and blocks. The following example illustrates the +The configuration file uses the same _HCL_ syntax as `.tf` and `.tofu` files, +but with different attributes and blocks. The following example illustrates the general syntax; see the following section for information on the meaning of each of these settings: diff --git a/website/docs/language/files/dependency-lock.mdx b/website/docs/language/files/dependency-lock.mdx index a0137b499f..24c4f4d514 100644 --- a/website/docs/language/files/dependency-lock.mdx +++ b/website/docs/language/files/dependency-lock.mdx @@ -39,8 +39,8 @@ to ensure that OpenTofu will always select the same module version. The dependency lock file is a file that belongs to the configuration as a whole, rather than to each separate module in the configuration. For that reason OpenTofu creates it and expects to find it in your current working directory -when you run OpenTofu, which is also the directory containing the `.tf` files -for the root module of your configuration. +when you run OpenTofu, which is also the directory containing the `.tf` or +`.tofu` files for the root module of your configuration. The lock file is always named `.terraform.lock.hcl`, and this name is intended to signify that it is a lock file for various items that OpenTofu caches in @@ -54,8 +54,8 @@ would discuss potential changes to your configuration itself. The dependency lock file uses the same low-level syntax as the main OpenTofu language, but the dependency lock file is not itself an OpenTofu language -configuration file. It is named with the suffix `.hcl` instead of `.tf` in -order to signify that difference. +configuration file. It is named with the suffix `.hcl` instead of `.tf` or +`.tofu` in order to signify that difference. ## Dependency Installation Behavior diff --git a/website/docs/language/files/index.mdx b/website/docs/language/files/index.mdx index d213d70f5e..40ceb834eb 100644 --- a/website/docs/language/files/index.mdx +++ b/website/docs/language/files/index.mdx @@ -8,13 +8,26 @@ description: >- ## File Extension -Code in the OpenTofu language is stored in plain text files with the `.tf` file -extension. There is also -[a JSON-based variant of the language](../../language/syntax/json.mdx) that is named with -the `.tf.json` file extension. +Code in the OpenTofu language is stored in plain text files with the `.tf` +or `.tofu` file extensions. There is also +[a JSON-based variant of the language](../../language/syntax/json.mdx) that is +named with the `.tf.json` or `.tofu.json` file extensions. Files containing OpenTofu code are often called _configuration files._ +### Extension Precedence + +When both `.tf` and `.tofu` files with the same base name are present in a +directory, OpenTofu will prioritize the `.tofu` file and ignore the `.tf` file. +For example: + +- If both `foo.tf` and `foo.tofu` exist in the same directory, OpenTofu will +only load `foo.tofu` and ignore `foo.tf`. + +This ensures that `.tofu` files always take precedence over `.tf` files when +both are available. This scenario can be useful for module authors who want +their modules to support both OpenTofu and Terraform. + ## Text Encoding Configuration files must always use UTF-8 encoding, and by convention @@ -23,8 +36,8 @@ line endings (CRLF), though both are accepted. ## Directories and Modules -A _module_ is a collection of `.tf` and/or `.tf.json` files kept together in a -directory. +A _module_ is a collection of one or many `.tf`, `.tf.json`, `.tofu`, +`.tofu.json` files kept together in a directory. An OpenTofu module only consists of the top-level configuration files in a directory; nested directories are treated as completely separate modules, and diff --git a/website/docs/language/files/override.mdx b/website/docs/language/files/override.mdx index 0e9801c0e9..d1934a4dd5 100644 --- a/website/docs/language/files/override.mdx +++ b/website/docs/language/files/override.mdx @@ -6,10 +6,10 @@ description: >- # Override Files -OpenTofu normally loads all of the `.tf` and `.tf.json` files within a -directory and expects each one to define a distinct set of configuration -objects. If two files attempt to define the same object, OpenTofu returns -an error. +OpenTofu normally loads all of the `.tf`, `.tofu`, `.tf.json` and `.tofu.json` +files within a directory and expects each one to define a distinct set of +configuration objects. If two files attempt to define the same object, OpenTofu +returns an error. In some rare cases, it is convenient to be able to override specific portions of an existing configuration object in a separate file. For example, a @@ -18,9 +18,20 @@ could be partially overridden using a programmatically-generated file in JSON syntax. For these rare situations, OpenTofu has special handling of any configuration -file whose name ends in `_override.tf` or `_override.tf.json`. This special -handling also applies to a file named literally `override.tf` or -`override.tf.json`. +file whose name ends in `_override.tf`, `_override.tofu`, `_override.tf.json` +or `_override.tofu.json`. This special handling also applies to a file named +literally `override.tf`, `override.tofu`, `override.tf.json` or +`override.tofu.json`. + +:::note +[Extension Precedence](./index.mdx#extension-precedence) is important when +dealing with override files. If both `foo_override.tf` and `foo_override.tofu` +exist in the same directory, OpenTofu will only load `foo_override.tofu` and +disregard `foo_override.tf`. The same rule applies to JSON-based files - if +both `foo_override.tofu.json` and `foo_override.tf.json` exist in the same +directory, OpenTofu will only load `foo_override.tofu.json` and ignore +`foo_override.tf.json`. +::: OpenTofu initially skips these _override files_ when loading configuration, and then afterwards processes each one in turn (in lexicographical order). For diff --git a/website/docs/language/modules/develop/index.mdx b/website/docs/language/modules/develop/index.mdx index 9c1a614b6e..bda0abd6ed 100644 --- a/website/docs/language/modules/develop/index.mdx +++ b/website/docs/language/modules/develop/index.mdx @@ -11,9 +11,9 @@ You can use modules to create lightweight abstractions, so that you can describe your infrastructure in terms of its architecture, rather than directly in terms of physical objects. -The `.tf` files in your working directory when you run [`tofu plan`](../../../cli/commands/plan.mdx) -or [`tofu apply`](../../../cli/commands/apply.mdx) together form the _root_ -module. That module may [call other modules](../../../language/modules/syntax.mdx#calling-a-child-module) +The `.tf` and/or `.tofu` files in your working directory when you run +[`tofu plan`](../../../cli/commands/plan.mdx) or [`tofu apply`](../../../cli/commands/apply.mdx) +together form the _root_ module. That module may [call other modules](../../../language/modules/syntax.mdx#calling-a-child-module) and connect them together by passing output values from one to input values of another. diff --git a/website/docs/language/modules/index.mdx b/website/docs/language/modules/index.mdx index 3da481d4f1..7241635a9d 100644 --- a/website/docs/language/modules/index.mdx +++ b/website/docs/language/modules/index.mdx @@ -7,8 +7,8 @@ description: >- # Modules _Modules_ are containers for multiple resources that are used together. A module -consists of a collection of `.tf` and/or `.tf.json` files kept together in a -directory. +consists of a collection of `.tf`, `.tofu`, `.tf.json`, and/or `.tofu.json` +files that are kept together in a directory. Modules are the main way to package and reuse resource configurations with OpenTofu. @@ -16,8 +16,8 @@ OpenTofu. ## The Root Module Every OpenTofu configuration has at least one module, known as its -_root module_, which consists of the resources defined in the `.tf` files in -the main working directory. +_root module_, which consists of the resources defined in the `.tf` or `.tofu` +files in the main working directory. ## Child Modules diff --git a/website/docs/language/modules/syntax.mdx b/website/docs/language/modules/syntax.mdx index 9bb9d1b60b..2145641558 100644 --- a/website/docs/language/modules/syntax.mdx +++ b/website/docs/language/modules/syntax.mdx @@ -10,8 +10,8 @@ description: >- A _module_ is a container for multiple resources that are used together. Every OpenTofu configuration has at least one module, known as its -_root module_, which consists of the resources defined in the `.tf` files in -the main working directory. +_root module_, which consists of the resources defined in the `.tf` and `.tofu` +files in the main working directory. A module can call other modules, which lets you include the child module's resources into the configuration in a concise way. Modules diff --git a/website/docs/language/syntax/json.mdx b/website/docs/language/syntax/json.mdx index 4ae872bbac..f60d68847f 100644 --- a/website/docs/language/syntax/json.mdx +++ b/website/docs/language/syntax/json.mdx @@ -20,8 +20,8 @@ be expressed in native syntax can also be expressed in JSON syntax, but some constructs are more complex to represent in JSON due to limitations of the JSON grammar. -OpenTofu expects native syntax for files named with a `.tf` suffix, and -JSON syntax for files named with a `.tf.json` suffix. +OpenTofu expects native syntax for files named with a `.tf` or `.tofu` suffix, +and JSON syntax for files named with a `.tf.json` or `.tofu.json` suffix. The low-level JSON syntax, just as with the native syntax, is defined in terms of a specification called _HCL_. It is not necessary to know all of the details @@ -30,6 +30,19 @@ summarizes the most important differences between native and JSON syntax. If you are interested, you can find a full definition of HCL's JSON syntax in [its specification](https://github.com/hashicorp/hcl/blob/main/json/spec.md). +### Extension Precedence + +When both `.tf.json` and `.tofu.json` files with the same base name are present +in a directory, OpenTofu will prioritize the `.tofu.json` file and ignore the +`.tf.json` file. For example: + +- If both `foo.tf.json` and `foo.tofu.json` exist in the same directory, +OpenTofu will only load `foo.tofu.json` and ignore `foo.tf.json`. + +This ensures that `.tofu.json` files always take precedence over `.tf.json` +files when both are available. This scenario can be useful for module authors +who want their modules to support both OpenTofu and Terraform. + ## JSON File Structure At the root of any JSON-based OpenTofu configuration is a JSON object. The