You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: www/docs/usage/commandline.md
+49-6
Original file line number
Diff line number
Diff line change
@@ -32,7 +32,7 @@ You can also set environment variables for tfswitch to override some configurati
32
32
For example:
33
33
34
34
```bash
35
-
export TF_VERSION=0.14.4
35
+
export TF_VERSION="0.14.4"
36
36
tfswitch # Will automatically switch to terraform version 0.14.4
37
37
```
38
38
@@ -43,7 +43,7 @@ tfswitch # Will automatically switch to terraform version 0.14.4
43
43
For example:
44
44
45
45
```bash
46
-
export TF_DEFAULT_VERSION=0.14.4
46
+
export TF_DEFAULT_VERSION="0.14.4"
47
47
tfswitch # Will automatically switch to terraform version 0.14.4
48
48
```
49
49
@@ -59,13 +59,32 @@ This can either be set to:
59
59
For example:
60
60
61
61
```bash
62
-
export TF_PRODUCT=opentofu
62
+
export TF_PRODUCT="opentofu"
63
63
tfswitch # Will install opentofu instead of terraform
64
64
```
65
65
66
+
### `TF_LOG_LEVEL`
67
+
68
+
`TF_LOG_LEVEL` environment variable can be set to override default log level.
69
+
70
+
- Supported log levels:
71
+
-`INFO`: includes `PANIC`, `FATAL`, `ERROR`
72
+
-`ERROR`: includes `PANIC`, `FATAL`, `ERROR`, `WARN`, `INFO`
73
+
-`NOTICE`: includes `PANIC`, `FATAL`, `ERROR`, `WARN`, `NOTICE`, `INFO`
74
+
-`DEBUG`: includes `PANIC`, `FATAL`, `ERROR`, `WARN`, `NOTICE`, `INFO`, `DEBUG`
75
+
-`TRACE`: includes `PANIC`, `FATAL`, `ERROR`, `WARN`, `NOTICE`, `INFO`, `DEBUG`, `TRACE`
76
+
- Any other log level value falls under default logging level
77
+
78
+
For example:
79
+
80
+
```bash
81
+
export TF_LOG_LEVEL="DEBUG"
82
+
tfswitch # Will output debug logs
83
+
```
84
+
66
85
### `TF_ARCH`
67
86
68
-
`TF_ARCH` environment variable can be set to override default CPU architecture for downloaded Terraform binary.
87
+
`TF_ARCH` environment variable can be set to override default CPU architecture of downloaded binaries.
69
88
70
89
- This can be set to any string, though incorrect values will result in download failure.
71
90
- Suggested values: `amd64`, `arm64`, `386`.
@@ -76,8 +95,32 @@ tfswitch # Will install opentofu instead of terraform
76
95
For example:
77
96
78
97
```bash
79
-
export TF_ARCH=amd64
80
-
tfswitch # Will install Terraform binary for amd64 architecture
98
+
export TF_ARCH="amd64"
99
+
tfswitch # Will install binary for amd64 architecture
100
+
```
101
+
102
+
### `TF_BINARY_PATH`
103
+
104
+
`tfswitch` defaults to install to the `/usr/local/bin/` directory (and falls back to `$HOME/bin/` otherwise). The target filename is resolved automatically based on the `product` parameter.
105
+
`TF_BINARY_PATH` environment variable can be set to specify a **full installation path** (directory + file name). If target directory does not exist, `tfswitch` falls back to `$HOME/bin/` directory.
106
+
107
+
For example:
108
+
109
+
```bash
110
+
export TF_BINARY_PATH="$HOME/bin/terraform"# Path to the file
111
+
tfswitch # Will install binary as $HOME/bin/terraform
112
+
```
113
+
114
+
### `TF_INSTALL_PATH`
115
+
116
+
`tfswitch` defaults to download binaries to the `$HOME/.terraform.versions/` directory.
117
+
`TF_INSTALL_PATH`environment variable can be set to specify a parent directory for `.terraform.versions` directory. Current user must have write permissions to the target directory. If the target directory does not exist, `tfswitch` will create it.
118
+
119
+
For example:
120
+
121
+
```bash
122
+
export TF_INSTALL_PATH="/tmp"# Path to the directory where `.terraform.versions` directory resides
123
+
tfswitch # Will download actual binary to /tmp/.terraform.versions/
Copy file name to clipboardexpand all lines: www/docs/usage/config-files.md
+65-18
Original file line number
Diff line number
Diff line change
@@ -9,8 +9,9 @@ tfswitch -c terraform_dir
9
9
10
10
## Use `version.tf` file
11
11
12
-
If a .tf file with the terraform constraints is included in the current directory, it should automatically download or switch to that terraform version.
13
-
For example, the following should automatically switch terraform to the lastest version:
12
+
If a `.tf` file with the version constraints is included in the current directory, `tfswitch` should automatically download or switch to that terraform version.
13
+
Also please refer to [Order of Terraform version definition precedence](general.md) page for more information on how `tfswitch` determines the version to use.
14
+
For example, the following should automatically switch to the latest available version newer than `0.12.8`:
14
15
15
16
```hcl
16
17
terraform {
@@ -30,21 +31,23 @@ terraform {
30
31
31
32
32
33
1. Create a `.tfswitchrc` file containing the desired version
33
-
2. For example, `echo "0.10.5" >> .tfswitchrc` for version 0.10.5 of terraform
34
-
3. Run the command `tfswitch` in the same directory as your`.tfswitchrc`
34
+
2. For example, `echo "0.10.5" >> .tfswitchrc` for version `0.10.5`
35
+
3. Run the command `tfswitch` in the same directory as this`.tfswitchrc` file
35
36
36
37
*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*
37
38
38
39
## Use `.tfswitch.toml` file (For non-admin users with limited privilege on their computers)
39
40
40
-
This is similiar to using a `.tfswitchrc` file, but you can specify a custom binary path for your terraform installation
41
+
`tfswitch` defaults to install to the `/usr/local/bin/` directory (and falls back to `$HOME/bin/` otherwise). The target filename is resolved automatically based on the `product` attribute ([see below](#setting-product-using-tfswitchtoml-file)). If you do not have write access to `/usr/local/bin/` directory, you can use the `.tfswitch.toml` file to specify a **full installation path** (directory + file name).
42
+
This is similar to using a `.tfswitchrc` file, but you specify a custom binary path for the installation:
41
43
42
44
43
45
44
46
45
-
1. Create a custom binary path. Ex: `mkdir $HOME/bin`
46
-
2. Add the path to your PATH. Ex: `export PATH=$PATH:$HOME/bin` (add this to your Bash profile or Zsh profile)
47
-
3. Pass `-b` or `--bin` parameter with your custom path to install Terraform. Ex: `tfswitch -b $HOME/bin/terraform 0.10.8`
47
+
1. Create a directory for the custom binary path. Ex: `mkdir -p "$HOME/bin/"`
48
+
2. Add the path to the directory to your `PATH` environment variable. Ex: `export PATH="$PATH:$HOME/bin"` (add this to your Bash profile or Zsh profile)
49
+
3. Pass `-b` or `--bin` parameter with the custom binary path as value (this must be a first level pointer inside the directory from above). Ex: `tfswitch -b "$HOME/bin/terraform" 0.10.8`
50
+
- If target directory for custom binary path does not exist, `tfswitch` falls back to `$HOME/bin/` directory
48
51
4. Optionally, you can create a `.tfswitch.toml` file in your home directory (`~/.tfswitch.toml`)
49
52
5. Your `~/.tfswitch.toml` file should look like this:
50
53
@@ -53,28 +56,27 @@ bin = "$HOME/bin/terraform"
53
56
version = "0.11.3"
54
57
```
55
58
56
-
6. Run `tfswitch` and it should automatically install the required terraform version in the specified binary path
59
+
6. Run `tfswitch` and it should automatically install the required version in the specified binary path
57
60
58
-
**NOTE**
59
-
60
-
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
61
-
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
61
+
Below is an example for `$HOME/.tfswitch.toml` on Windows:
62
62
63
63
```toml
64
64
bin = "C:\\Users\\<%USRNAME%>\\bin\\terraform.exe"
65
65
```
66
66
67
-
## Setting the default version using `.tfswitch.toml` file
67
+
## Setting the default (fallback) version using `.tfswitch.toml` file
68
68
69
-
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
69
+
If `tfswsitch` is unable to determine the version to use, it errors out.
70
+
The `.tfswitch.toml` file can be configured with a `default-version` attribute for `tfswitch` to use a particular version, if no other sources of versions are found
70
71
71
72
```toml
72
73
default-version = "1.5.4"
73
74
```
74
75
75
76
## Setting product using `.tfswitch.toml` file
76
77
77
-
The `.tfswitch.toml` file can be configured with a `product` attribute to configure tfswitch to use Terraform or OpenTofu, by default:
78
+
`tfswitch` defaults to install Terraform binaries.
79
+
The `.tfswitch.toml` file can be configured with a `product` attribute for `tfswitch` to use either Terraform or OpenTofu by default:
78
80
79
81
```toml
80
82
product = "opentofu"
@@ -86,10 +88,55 @@ or
86
88
product = "terraform"
87
89
```
88
90
91
+
## Setting log level using `.tfswitch.toml` file
92
+
93
+
`tfswitch` defaults to `INFO` log level.
94
+
The `.tfswitch.toml` file can be configured with a `log-level` attribute for `tfswitch` to use non-default logging verbosity:
95
+
96
+
```toml
97
+
log-level = "INFO"
98
+
```
99
+
100
+
- Supported log levels:
101
+
-`INFO`: includes `PANIC`, `FATAL`, `ERROR`
102
+
-`ERROR`: includes `PANIC`, `FATAL`, `ERROR`, `WARN`, `INFO`
103
+
-`NOTICE`: includes `PANIC`, `FATAL`, `ERROR`, `WARN`, `NOTICE`, `INFO`
104
+
-`DEBUG`: includes `PANIC`, `FATAL`, `ERROR`, `WARN`, `NOTICE`, `INFO`, `DEBUG`
105
+
-`TRACE`: includes `PANIC`, `FATAL`, `ERROR`, `WARN`, `NOTICE`, `INFO`, `DEBUG`, `TRACE`
106
+
- Any other log level value falls under default logging level
107
+
108
+
## Overriding CPU architecture type for the downloaded binary using `.tfswitch.toml` file
109
+
110
+
CPU architecture of the downloaded binaries defaults to `tfswitch`'s host architecture.
111
+
The `.tfswitch.toml` file can be configured with a `arch` attribute for `tfswitch` to download binary of non-default architecture type:
112
+
113
+
```toml
114
+
arch = "arm64"
115
+
```
116
+
117
+
- This can be set to any string, though incorrect values will result in download failure.
## Overriding installation directory, where actual binaries are stored, using `.tfswitch.toml` file
124
+
125
+
`tfswitch` defaults to download binaries to the `$HOME/.terraform.versions/` directory.
126
+
The `.tfswitch.toml` file can be configured with a `install` attribute to specify a parent directory for `.terraform.versions` directory.
127
+
128
+
```toml
129
+
install = "/tmp"
130
+
```
131
+
132
+
**NOTE**:
133
+
- Current user must have write permissions to the target directory
134
+
- If the target directory does not exist, `tfswitch` will create it
135
+
89
136
## Use `terragrunt.hcl` file
90
137
91
-
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.
92
-
For example, the following should automatically switch terraform to the lastest version 0.13:
138
+
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.
139
+
For example, the following should automatically switch Terraform to the latest version 0.13:
0 commit comments