From d04c42b3c27b1d8c5209c05b1f9cc2738d75377c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Klintrup?= Date: Fri, 2 Feb 2024 23:43:57 +0100 Subject: [PATCH 1/4] add tofu command to tenv. update help messages --- cmd/tenv/tenv.go | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/cmd/tenv/tenv.go b/cmd/tenv/tenv.go index d0db4b16..4ab566dc 100644 --- a/cmd/tenv/tenv.go +++ b/cmd/tenv/tenv.go @@ -30,8 +30,9 @@ import ( const ( rootVersionHelp = "Display tenv current version." - tfHelp = "subcommands that help manage several version of Terraform (https://www.terraform.io)." - tgHelp = "subcommands that help manage several version of Terragrunt (https://terragrunt.gruntwork.io/)." + tfHelp = "subcommand to manage several versions of Terraform (https://www.terraform.io)." + tgHelp = "subcommand to manage several versions of Terragrunt (https://terragrunt.gruntwork.io/)." + tofuHelp = "subcommand to manage several versions of OpenTofu (https://opentofu.org)." ) // can be overridden with ldflags. @@ -60,7 +61,7 @@ func main() { func initRootCmd(conf *config.Config) *cobra.Command { rootCmd := &cobra.Command{ Use: "tenv", - Long: "tenv help manage several version of OpenTofu (https://opentofu.org).", + Long: "tenv help manage several versions of OpenTofu (https://opentofu.org), Terraform (https://www.terraform.io) and Terragrunt (https://terragrunt.gruntwork.io/).", Version: version, } @@ -75,6 +76,17 @@ func initRootCmd(conf *config.Config) *cobra.Command { } initSubCmds(rootCmd, conf, builder.BuildTofuManager(conf), tofuParams) + // Add this in your main function, after the tfCmd and before the tgCmd + tofuCmd := &cobra.Command{ + Use: "tofu", + Short: tofuHelp, + Long: tofuHelp, + } + + initSubCmds(tofuCmd, conf, builder.BuildTofuManager(conf), tofuParams) + + rootCmd.AddCommand(tofuCmd) + tfCmd := &cobra.Command{ Use: "tf", Short: tfHelp, From 35f7a8423f2f748be456402cb14831166f88d9f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Klintrup?= Date: Sat, 3 Feb 2024 00:03:26 +0100 Subject: [PATCH 2/4] Update tenv usage instructions --- README.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8e9afc65..4b8534d3 100644 --- a/README.md +++ b/README.md @@ -142,12 +142,16 @@ TODO ## Usage -**tenv** supports [OpenTofu](https://opentofu.org) and [Terraform](https://www.terraform.io/). To manage each binary you can use `tenv` subcommands (manage OpenTofu versions) or `tenv tf` subcommands (manage Terraform versions). Below is a list of commands that use actual subcommands: -TOFUENV_ +**tenv** supports [OpenTofu](https://opentofu.org), [Terragrunt](https://terragrunt.gruntwork.io/) and [Terraform](https://www.terraform.io/). To manage each binary you can use `tenv `. Below is a list of tools and commands that use actual subcommands: +| tool | description | +| ---- | ---------------------------------------------- | +| `tofu` | [OpenTofu](https://opentofu.org) | +| `tf` | [Terraform](https://www.terraform.io/) | +| `tg` | [Terragrunt](https://terragrunt.gruntwork.io/) | -
tenv (tool) install [version]
-Install a requested version of (tool) (into (TOOL)_ROOT directory from (TOOL)_REMOTE url). +
tenv <tool> install [version]
+Install a requested version of <tool> (into <TOOL>_ROOT directory from <TOOL>_REMOTE url). Without a parameter, the version to use is resolved automatically via TOFUENV_TOFU_VERSION or [`.opentofu-version`](#opentofu-version-file) files (searched in the working directory, user home directory, and TOFUENV_ROOT directory). @@ -163,17 +167,17 @@ If a parameter is passed, available options include: See [required_version](https://opentofu.org/docs/language/settings#specifying-a-required-opentofu-version) docs. ```console -tenv install 1.6.0-beta5 -tenv install "~> 1.6.0" -tenv install latest -tenv install latest-stable -tenv install latest-allowed -tenv install min-required +tenv install 1.6.0-beta5 +tenv install "~> 1.6.0" +tenv install latest +tenv install latest-stable +tenv install latest-allowed +tenv install min-required ```
-
tenv (tool) use
+
tenv <tool> use
Switch the default OpenTofu version to use (set in [`.opentofu-version`](#opentofu-version-file) file in TOFUENV_ROOT). @@ -196,7 +200,7 @@ tenv use latest-allowed ```
-
tenv (tool) detect
+
tenv <tool> detect
Detect the used version of OpenTofu for the working directory. @@ -206,7 +210,7 @@ OpenTofu 1.6.0 will be run from this directory. ```
-
tenv (tool) reset
+
tenv <tool> reset
Reset used version of OpenTofu (remove .opentofu-version file from TOFUENV_ROOT). ```console @@ -215,7 +219,7 @@ tenv reset
-
tenv (tool) uninstall [version]
+
tenv <tool> uninstall [version]
Uninstall a specific version of OpenTofu (remove it from TOFUENV_ROOT directory without interpretation). ```console @@ -223,7 +227,7 @@ tenv uninstall v1.6.0-alpha4 ```
-
tenv (tool) list
+
tenv <tool> list
List installed OpenTofu versions (located in TOFUENV_ROOT directory), sorted in ascending version order. @@ -237,7 +241,7 @@ $ tenv list
-
tenv (tool) list-remote
+
tenv <tool> list-remote
List installable OpenTofu versions (from TOFUENV_REMOTE url), sorted in ascending version order. `tenv list-remote` has a `--descending`, `-d` flag to sort in descending order. From 890c6428fe25192d2dca84899e7ef71b263dbfbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Klintrup?= Date: Sat, 3 Feb 2024 11:59:42 +0100 Subject: [PATCH 3/4] Refactor documentation to improve performance and readability --- README.md | 134 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 74 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 4b8534d3..1aec210c 100644 --- a/README.md +++ b/README.md @@ -144,29 +144,30 @@ TODO ## Usage **tenv** supports [OpenTofu](https://opentofu.org), [Terragrunt](https://terragrunt.gruntwork.io/) and [Terraform](https://www.terraform.io/). To manage each binary you can use `tenv `. Below is a list of tools and commands that use actual subcommands: -| tool | description | -| ---- | ---------------------------------------------- | -| `tofu` | [OpenTofu](https://opentofu.org) | -| `tf` | [Terraform](https://www.terraform.io/) | -| `tg` | [Terragrunt](https://terragrunt.gruntwork.io/) | +| tool | env vars | description | +| ------ | -------------------------- | ---------------------------------------------- | +| `tofu` | [TOFUENV_](#tofu-env-vars) | [OpenTofu](https://opentofu.org) | +| `tf` | [TFENV_](#tf-env-vars) | [Terraform](https://www.terraform.io/) | +| `tg` | [TG_](#tg-env-vars) | [Terragrunt](https://terragrunt.gruntwork.io/) |
tenv <tool> install [version]
Install a requested version of <tool> (into <TOOL>_ROOT directory from <TOOL>_REMOTE url). -Without a parameter, the version to use is resolved automatically via TOFUENV_TOFU_VERSION or [`.opentofu-version`](#opentofu-version-file) files -(searched in the working directory, user home directory, and TOFUENV_ROOT directory). -Use "latest-stable" when none are found. +Without a parameter, the version to use is resolved automatically via the relevant `_VERSION` [environment variable](#environment-variables) or [version file](#version-files) +(searched in the working directory, user home directory, and `_ROOT` directory). + +Will default to "latest-stable" when no specified version is found. If a parameter is passed, available options include: - an exact [Semver 2.0.0](https://semver.org/) version string to install -- a [version constraint](https://opentofu.org/docs/language/expressions/version-constraints) string (checked against versions available at TOFUENV_REMOTE url) -- `latest` or `latest-stable` (checked against versions available at TOFUENV_REMOTE url) -- `latest-allowed` or `min-required` to scan your OpenTofu files to detect which version is maximally allowed or minimally required. - -See [required_version](https://opentofu.org/docs/language/settings#specifying-a-required-opentofu-version) docs. +- a [version constraint](https://opentofu.org/docs/language/expressions/version-constraints) string (checked against versions available at `_REMOTE` url) +- `latest` or `latest-stable` (checked against versions available at `_REMOTE` url) +- `latest-allowed` or `min-required` to scan your IAC files to detect which version is maximally allowed or minimally required. + See [required_version](#required_version) docs. ```console +tenv install tenv install 1.6.0-beta5 tenv install "~> 1.6.0" tenv install latest @@ -177,79 +178,77 @@ tenv install min-required
-
tenv <tool> use
+
tenv <tool> use [version]
-Switch the default OpenTofu version to use (set in [`.opentofu-version`](#opentofu-version-file) file in TOFUENV_ROOT). +Switch the default OpenTofu version to use (set in [version file](#version-files) ). -`tenv use` has a `--working-dir`, `-w` flag to write [`.opentofu-version`](#opentofu-version-file) file in working directory. +`tenv use` has a `--working-dir`, `-w` flag to write [version file](#version-files) file in working directory. Available parameter options: -- an exact [Semver 2.0.0](https://semver.org/) version string to use -- a [version constraint](https://opentofu.org/docs/language/expressions/version-constraints) string (checked against available in TOFUENV_ROOT directory) -- latest or latest-stable (checked against available in TOFUENV_ROOT directory) -- latest-allowed or min-required to scan your OpenTofu files to detect which version is maximally allowed or minimally required. - -See [required_version](https://opentofu.org/docs/language/settings#specifying-a-required-opentofu-version) docs. +- an exact [Semver 2.0.0](https://semver.org/) version string to install +- a [version constraint](https://opentofu.org/docs/language/expressions/version-constraints) string (checked against versions available at `_REMOTE` url) +- `latest` or `latest-stable` (checked against versions available at `_REMOTE` url) +- `latest-allowed` or `min-required` to scan your IAC files to detect which version is maximally allowed or minimally required. + See [required_version](#required_version) docs. ```console -tenv use min-required -tenv use v1.6.0-beta5 -tenv use latest -tenv use latest-allowed +tenv use min-required +tenv use v1.6.0-beta5 +tenv use latest +tenv use latest-allowed ```
tenv <tool> detect
-Detect the used version of OpenTofu for the working directory. +Detect the used version of tool for the working directory. ```console -$ tenv detect +$ tenv tofu detect OpenTofu 1.6.0 will be run from this directory. ```
tenv <tool> reset
-Reset used version of OpenTofu (remove .opentofu-version file from TOFUENV_ROOT). +Reset used version of tool (remove `.-version` file from `_ROOT`). ```console -tenv reset +tenv reset ```
tenv <tool> uninstall [version]
-Uninstall a specific version of OpenTofu (remove it from TOFUENV_ROOT directory without interpretation). +Uninstall a specific version of OpenTofu (remove it from `_ROOT` directory without interpretation). ```console -tenv uninstall v1.6.0-alpha4 +tenv uninstall v1.6.0-alpha4 ```
tenv <tool> list
-List installed OpenTofu versions (located in TOFUENV_ROOT directory), sorted in ascending version order. +List installed tool versions (located in `_ROOT` directory), sorted in ascending version order. -`tenv list` has a `--descending`, `-d` flag to sort in descending order. +`tenv list` has a `--descending`, `-d` flag to sort in descending order. ```console -$ tenv list +$ tenv list 1.6.0-rc1 * 1.6.0 (set by /home/dvaumoron/.tenv/.opentofu-version) ```
-
tenv <tool> list-remote
-List installable OpenTofu versions (from TOFUENV_REMOTE url), sorted in ascending version order. +List installable tool versions (from `TOOL_REMOTEHappy_REMOTE url), sorted in ascending version order. -`tenv list-remote` has a `--descending`, `-d` flag to sort in descending order. +`tenv list-remote` has a `--descending`, `-d` flag to sort in descending order. -`tenv list-remote` has a `--stable`, `-s` flag to display only stable version. +`tenv list-remote` has a `--stable`, `-s` flag to display only stable version. ```console -$ tenv list-remote +$ tenv list-remote 1.6.0-alpha1 1.6.0-alpha2 1.6.0-alpha3 @@ -279,29 +278,30 @@ Usage: tenv tf detect [flags] Flags: - -f, --force-remote force search on versions available at TFENV_REMOTE url - -h, --help help for detect - -k, --key-file string local path to PGP public key file (replace check against remote one) - -n, --no-install disable installation of missing version - -u, --remote-url string remote url to install from (default "https://releases.hashicorp.com/terraform") + -f, --force-remote force search on versions available at TFENV_REMOTE url + -h, --help help for detect + -k, --key-file string local path to PGP public key file (replace check against remote one) + -n, --no-install disable installation of missing version + -c, --remote-conf string path to remote configuration file (advanced settings) + -u, --remote-url string remote url to install from Global Flags: - -r, --root-path string local path to install versions of OpenTofu and Terraform (default "/home/dvaumoron/.tenv") + -r, --root-path string local path to install versions of OpenTofu and Terraform (default "/home/nonroot/.tenv") -v, --verbose verbose output ``` ```console -$ tenv use -h +$ tenv tofu use -h Switch the default OpenTofu version to use (set in .opentofu-version file in TOFUENV_ROOT) Available parameter options: - an exact Semver 2.0.0 version string to use -- a version constraint string (checked against versions available in TOFUENV_ROOT directory) -- `latest` or `latest-stable` (checked against versions available in TOFUENV_ROOT directory) -- `latest-allowed` or `min-required` to scan your OpenTofu files to detect which version is maximally allowed or minimally required. +- a version constraint string (checked against version available in TOFUENV_ROOT directory) +- latest or latest-stable (checked against version available in TOFUENV_ROOT directory) +- latest-allowed or min-required to scan your OpenTofu files to detect which version is maximally allowed or minimally required. Usage: - tenv use version [flags] + tenv tofu use version [flags] Flags: -f, --force-remote force search on versions available at TOFUENV_REMOTE url @@ -309,11 +309,12 @@ Flags: -h, --help help for use -k, --key-file string local path to PGP public key file (replace check against remote one) -n, --no-install disable installation of missing version - -u, --remote-url string remote url to install from (default "https://api.github.com/repos/opentofu/opentofu/releases") + -c, --remote-conf string path to remote configuration file (advanced settings) + -u, --remote-url string remote url to install from -w, --working-dir create .opentofu-version file in working directory Global Flags: - -r, --root-path string local path to install versions of OpenTofu and Terraform (default "/home/dvaumoron/.tenv") + -r, --root-path string local path to install versions of OpenTofu and Terraform (default "/home/nonroot/.tenv") -v, --verbose verbose output ```
@@ -322,7 +323,7 @@ Global Flags: ## Environment variables -tenv commands support two groups of environment variables, one for managing [OpenTofu](https://opentofu.org) and one for managing [Terraform](https://www.terraform.io/) +tenv commands support multiple groups of environment variables, [OpenTofu](https://opentofu.org), [Terraform](https://www.terraform.io/) and [TerraGrunt](https://terragrunt.gruntwork.io/). ### OpenTofu environment variables @@ -352,7 +353,6 @@ Write 1.6.0 in /home/dvaumoron/.tenv/.opentofu-version ```
-
TOFUENV_FORCE_REMOTE
String (Default: false) @@ -361,7 +361,6 @@ If set to true **tenv** detection of needed version will skip local check and ve `tenv` subcommands `detect` and `use` support a `--force-remote`, `-f` flag version.
-
TOFUENV_OPENTOFU_PGP_KEY
String (Default: "") @@ -370,7 +369,6 @@ Allow to specify a local file path to OpenTofu PGP public key, if not present do **tenv** subcommands `detect`, `ìnstall` and `use` support a `--key-file`, `-k` flag version.
-
TOFUENV_REMOTE
String (Default: https://api.github.com/repos/opentofu/opentofu/releases) @@ -379,7 +377,6 @@ To install OpenTofu from a remote other than the default (must comply with [Gith `tenv tf` subcommands `detect`, `install`, `list-remote` and `use` support a `--remote-url`, `-u` flag version.
-
TOFUENV_ROOT
String (Default: `${HOME}/.tenv`) @@ -397,7 +394,6 @@ Allow to specify a GitHub token to increase [GitHub Rate limits for the REST API `tenv` subcommands `detect`, `install`, `list-remote` and `use` support a `--github-token`, `-t` flag version.
-
TOFUENV_VERBOSE
String (Default: false) @@ -406,7 +402,6 @@ Active the verbose display of **tenv**. `tenv` support a `--verbose`, `-v` flag version.
-
TOFUENV_TOFU_VERSION
String (Default: "") @@ -607,21 +602,40 @@ or terragrunt.hcl.json TODO ### .tf files + or .tf.json files TODO +### required_version + +Will scan through your IAC files and identify the latest allowed version as defined in the relevant files. + +Currently the format for [Terraform required_version](https://developer.hashicorp.com/terraform/language/settings#specifying-a-required-terraform-version) and [OpenTofu required_version](https://opentofu.org/docs/language/settings#specifying-a-required-opentofu-version) are very similar, however this may change over time, always refer to docs for the latest format specification. + +example: + +```HCL +version = ">= 1.2.0, < 2.0.0" +``` + +This would identify the latest version at or above 1.2.0 and below 2.0.0 + + ## Technical details ### Project binaries #### tofu + The `tofu` command in this project is a proxy to OpenTofu's `tofu` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TOFUENV_TOFU_VERSION](#tofuenv_tofu_version) environment variable or [`.opentofu-version`](#opentofu-version-file) file). #### terraform + The `terraform` command in this project is a proxy to HashiCorp's `terraform` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TFENV_TERRAFORM_VERSION](#tfenv_terraform_version) environment variable or `.terraform-version` file). #### terragrunt + The `terragrunt` command in this project is a proxy to Gruntwork's `terragrunt` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TG_VERSION](#tg_version) environment variable or `.terragrunt-version` file). ### Terraform support From a55c84a80a012507a1e9292b167970df0666e02b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Klintrup?= Date: Sat, 3 Feb 2024 12:03:18 +0100 Subject: [PATCH 4/4] Update environment variable links in README.md --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1aec210c..d9af3686 100644 --- a/README.md +++ b/README.md @@ -628,19 +628,19 @@ This would identify the latest version at or above 1.2.0 and below 2.0.0 #### tofu -The `tofu` command in this project is a proxy to OpenTofu's `tofu` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TOFUENV_TOFU_VERSION](#tofuenv_tofu_version) environment variable or [`.opentofu-version`](#opentofu-version-file) file). +The `tofu` command in this project is a proxy to OpenTofu's `tofu` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TOFUENV_TOFU_VERSION](#tofu-env-vars) environment variable or [`.opentofu-version`](#opentofu-version-file) file). #### terraform -The `terraform` command in this project is a proxy to HashiCorp's `terraform` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TFENV_TERRAFORM_VERSION](#tfenv_terraform_version) environment variable or `.terraform-version` file). +The `terraform` command in this project is a proxy to HashiCorp's `terraform` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TFENV_TERRAFORM_VERSION](#tf-env-vars) environment variable or `.terraform-version` file). #### terragrunt -The `terragrunt` command in this project is a proxy to Gruntwork's `terragrunt` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TG_VERSION](#tg_version) environment variable or `.terragrunt-version` file). +The `terragrunt` command in this project is a proxy to Gruntwork's `terragrunt` command managed by `tenv`. The default resolution strategy is latest-allowed (without [TG_VERSION](#tg-env-vars) environment variable or `.terragrunt-version` file). ### Terraform support -tenv relies on `.terraform-version` files, [TFENV_HASHICORP_PGP_KEY](#tfenv_hashicorp_pgp_key), [TFENV_REMOTE](#tfenv_remote) and [TFENV_TERRAFORM_VERSION](#tfenv_terraform_version) specifically to manage Terraform versions. +tenv relies on `.terraform-version` files, [TFENV_HASHICORP_PGP_KEY](#tf-env-vars), [TFENV_REMOTE](#tf-env-vars) and [TFENV_TERRAFORM_VERSION](#tf-env-vars) specifically to manage Terraform versions. `tenv tf` have the same managing subcommands for Terraform versions (`detect`, `install`, `list`, `list-remote`, `reset`, `uninstall` and `use`). @@ -648,7 +648,7 @@ tenv checks the Terraform PGP signature (there is no cosign signature available) ### Terragrunt support -tenv relies on `.terragrunt-version` files, [TG_REMOTE](#tg_remote) and [TG_VERSION](#tg_version) specifically to manage Terragrunt versions. +tenv relies on `.terragrunt-version` files, [TG_REMOTE](#tg-env-vars) and [TG_VERSION](#tg-env-vars) specifically to manage Terragrunt versions. `tenv tg` have the same managing subcommands for Terragrunt versions (`detect`, `install`, `list`, `list-remote`, `reset`, `uninstall` and `use`).