Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: TOML file belongs in Home dir only #534

Merged
merged 1 commit into from
Jan 20, 2025
Merged

docs: TOML file belongs in Home dir only #534

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion www/docs/usage/ci-cd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
## Automatically switch with bash

Add the following to the end of your `~/.bashrc` file:
(Use either `.tfswitchrc` or `.tfswitch.toml` or `.terraform-version`)
(Use either `.tfswitchrc` or `.terraform-version`)

```sh
cdtfswitch(){
Expand Down
34 changes: 17 additions & 17 deletions www/docs/usage/config-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@ tfswitch --chdir terraform_dir
tfswitch -c terraform_dir
```

## Use version.tf file
## Use `version.tf` file

If a .tf file with the terraform constraints is included in the current directory, it should automatically download or switch to that terraform version.
For example, the following should automatically switch terraform to the lastest version:

```
```hcl
terraform {
required_version = ">= 0.12.9"

Expand All @@ -25,7 +25,7 @@ terraform {

![versiontf](../static/versiontf.gif "Use version.tf")

## Use .tfswitchrc file
## Use `.tfswitchrc` file

![tfswitchrc](../static/tfswitch-v6.gif)

Expand All @@ -35,18 +35,18 @@ terraform {

*Instead of a `.tfswitchrc` file, a `.terraform-version` file may be used for compatibility with [`tfenv`](https://github.com/tfutils/tfenv#terraform-version-file) and other tools which use it*

## Use .tfswitch.toml file (For non-admin - users with limited privilege on their computers)
## Use `.tfswitch.toml` file (For non-admin users with limited privilege on their computers)

This is similiar to using a .tfswitchrc file, but you can specify a custom binary path for your terraform installation
This is similiar to using a `.tfswitchrc` file, but you can specify a custom binary path for your terraform installation

![toml1](../static/tfswitch-v7.gif)
![toml2](../static/tfswitch-v8.gif)

1. Create a custom binary path. Ex: `mkdir $HOME/bin`
2. Add the path to your PATH. Ex: `export PATH=$PATH:$HOME/bin` (add this to your bash profile or zsh profile)
3. Pass -b or --bin parameter with your custom path to install terraform. Ex: `tfswitch -b $HOME/bin/terraform 0.10.8 `
4. Optionally, you can create a `.tfswitch.toml` file in your terraform directory(current directory) OR in your home directory(~/.tfswitch.toml). The toml file in the current directory has a higher precedence than toml file in the home directory
5. Your `.tfswitch.toml` file should look like this:
2. Add the path to your PATH. Ex: `export PATH=$PATH:$HOME/bin` (add this to your Bash profile or Zsh profile)
3. Pass `-b` or `--bin` parameter with your custom path to install Terraform. Ex: `tfswitch -b $HOME/bin/terraform 0.10.8`
4. Optionally, you can create a `.tfswitch.toml` file in your home directory (`~/.tfswitch.toml`)
5. Your `~/.tfswitch.toml` file should look like this:

```toml
bin = "$HOME/bin/terraform"
Expand All @@ -57,24 +57,24 @@ version = "0.11.3"

**NOTE**

1. For linux users that do not have write permission to `/usr/local/bin/`, `tfswitch` will attempt to install terraform at `$HOME/bin`. Run `export PATH=$PATH:$HOME/bin` to append bin to PATH
2. For windows host, `tfswitch` need to be run under `Administrator` mode, and `$HOME/.tfswitch.toml` with `bin` must be defined (with a valid path) as minimum, below is an example for `$HOME/.tfswitch.toml` on windows
1. For Linux users that do not have write permission to `/usr/local/bin/`, `tfswitch` will attempt to install terraform at `$HOME/bin`. Run `export PATH=$PATH:$HOME/bin` to append bin to PATH
2. For Windows host, `tfswitch` need to be run under `Administrator` mode, and `$HOME/.tfswitch.toml` with `bin` must be defined (with a valid path) as minimum, below is an example for `$HOME/.tfswitch.toml` on windows

```toml
bin = "C:\\Users\\<%USRNAME%>\\bin\\terraform.exe"
```

## Setting the default version using .tfswitch.toml file
## Setting the default version using `.tfswitch.toml` file

The .tfswitch.toml file can be configured with a `default-version` attribute to configure tfswitch a particular version, if no other sources of versions are found
The `.tfswitch.toml` file can be configured with a `default-version` attribute to configure tfswitch a particular version, if no other sources of versions are found

```toml
default-version = "1.5.4"
```

## Setting product using .tfswitch.toml file
## Setting product using `.tfswitch.toml` file

The .tfswitch.toml file can be configured with a `product` attribute to configure tfswitch to use Terraform or OpenTofu, by default:
The `.tfswitch.toml` file can be configured with a `product` attribute to configure tfswitch to use Terraform or OpenTofu, by default:

```toml
product = "opentofu"
Expand All @@ -86,9 +86,9 @@ or
product = "terraform"
```

## Use terragrunt.hcl file
## Use `terragrunt.hcl` file

If a terragrunt.hcl file with the terraform constraint is included in the current directory, it should automatically download or switch to that terraform version.
If a terragrunt.hcl file with the terraform constraint is included in the current directory, it should automatically download or switch to that terraform version.
For example, the following should automatically switch terraform to the lastest version 0.13:

```hcl
Expand Down
11 changes: 5 additions & 6 deletions www/docs/usage/general.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,11 @@
| Order | Method |
| --- | ----------- |
| 1 | `$HOME/.tfswitch.toml` (`version` parameter) |
| 2 | `.tfswitch.toml` (`version` parameter) |
| 3 | `.tfswitchrc` (version as a string) |
| 4 | `.terraform-version` (version as a string) |
| 5 | Terraform root module (`required_version` constraint) |
| 6 | `terragrunt.hcl` (`terraform_version_constraint` parameter) |
| 7 | Environment variable (`TF_VERSION`) |
| 2 | `.tfswitchrc` (version as a string) |
| 3 | `.terraform-version` (version as a string) |
| 4 | Terraform root module (`required_version` constraint) |
| 5 | `terragrunt.hcl` (`terraform_version_constraint` parameter) |
| 6 | Environment variable (`TF_VERSION`) |
yermulnik marked this conversation as resolved.
Show resolved Hide resolved

With 1 being the **lowest** precedence and 7 — the **highest**
*(If you disagree with this order of precedence, please open an issue)*
Loading