1
2## How to use:
3### Use dropdown menu to select version
4<img src="https://s3.us-east-2.amazonaws.com/kepler-images/warrensbox/tfswitch/tfswitch.gif" alt="drawing" style="width: 600px;"/>
5
61.  You can switch between different versions of terraform by typing the command `tfswitch` on your terminal.
72.  Select the version of terraform you require by using the up and down arrow.
83.  Hit **Enter** to select the desired version.
9
10The most recently selected versions are presented at the top of the dropdown.
11
12### Supply version on command line
13<img src="https://s3.us-east-2.amazonaws.com/kepler-images/warrensbox/tfswitch/tfswitch-v4.gif" alt="drawing" style="width: 600px;"/>
14
151. You can also supply the desired version as an argument on the command line.
162. For example, `tfswitch 0.10.5` for version 0.10.5 of terraform.
173. Hit **Enter** to switch.
18
19### See all versions including beta, alpha and release candidates(rc)
20<img src="https://s3.us-east-2.amazonaws.com/kepler-images/warrensbox/tfswitch/tfswitch-v5.gif" alt="drawing" style="width: 600px;"/>
21
221. Display all versions including beta, alpha and release candidates(rc).
232. For example, `tfswitch -l` or `tfswitch --list-all` to see all versions.
243. Hit **Enter** to select the desired version.
25### Use environment variables
26You can also set the `TF_VERSION` environment variable to your desired terraform version.
27For example:
28```bash
29export TF_VERSION=0.14.4
30tfswitch #will automatically switch to terraform version 0.14.4
31```
32### Install latest version only
331. Install the latest stable version only.
342. Run `tfswitch -u` or `tfswitch --latest`.
353. Hit **Enter** to install.
36### Install latest implicit version for stable releases
371. Install the latest implicit stable version.
382. Ex: `tfswitch -s 0.13` or `tfswitch --latest-stable 0.13` downloads 0.13.6 (latest) version.
393. Hit **Enter** to install.
40### Install latest implicit version for beta, alpha and release candidates(rc)
411. Install the latest implicit pre-release version.
422. Ex: `tfswitch -p 0.13` or `tfswitch --latest-pre 0.13` downloads 0.13.0-rc1 (latest) version.
433. Hit **Enter** to install.
44### Use version.tf file
45If a .tf file with the terraform constrain 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:
46```
47terraform {
48  required_version = ">= 0.12.9"
49
50  required_providers {
51    aws        = ">= 2.52.0"
52    kubernetes = ">= 1.11.1"
53  }
54}
55```
56<img src="https://s3.us-east-2.amazonaws.com/kepler-images/warrensbox/tfswitch/versiontf.gif" alt="drawing" style="width: 600px;"/>
57
58### Use .tfswitch.toml file  (For non-admin - users with limited privilege on their computers)
59This is similiar to using a .tfswitchrc file, but you can specify a custom binary path for your terraform installation
60
61<img src="https://s3.us-east-2.amazonaws.com/kepler-images/warrensbox/tfswitch/tfswitch-v7.gif" alt="drawing" style="width: 600px;"/>
62<img src="https://s3.us-east-2.amazonaws.com/kepler-images/warrensbox/tfswitch/tfswitch-v8.gif" alt="drawing" style="width: 600px;"/>
63
641. Create a custom binary path. Ex: `mkdir /Users/warrenveerasingam/bin` (replace warrenveerasingam with your username)
652. Add the path to your PATH. Ex: `export PATH=$PATH:/Users/warrenveerasingam/bin` (add this to your bash profile or zsh profile)
663. Pass -b or --bin parameter with your custom path to install terraform. Ex: `tfswitch -b /Users/warrenveerasingam/bin/terraform 0.10.8 `
674. 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
685. Your `.tfswitch.toml` file should look like this:
69```ruby
70bin = "/Users/warrenveerasingam/bin/terraform"
71version = "0.11.3"
72```
734. Run `tfswitch` and it should automatically install the required terraform version in the specified binary path
74
75**NOTE**
761. 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
772. 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
78
79```toml
80bin = "C:\\Users\\<%USRNAME%>\\bin\\terraform.exe"
81```
82### Use .tfswitchrc file
83<img src="https://s3.us-east-2.amazonaws.com/kepler-images/warrensbox/tfswitch/tfswitch-v6.gif" alt="drawing" style="width: 600px;"/>
84
851. Create a `.tfswitchrc` file containing the desired version
862. For example, `echo "0.10.5" >> .tfswitchrc` for version 0.10.5 of terraform
873. Run the command `tfswitch` in the same directory as your `.tfswitchrc`
88
89*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*
90
91### Use terragrunt.hcl file
92If a terragrunt.hcl file with the terraform constrain 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:
93```ruby
94terragrunt_version_constraint = ">= 0.26, < 0.27"
95terraform_version_constraint  = ">= 0.13, < 0.14"
96...
97```
98
99### Get the version from a subdirectory
100```bash
101tfswitch --chdir terraform_dir
102tfswitch -c terraform_dir
103```
104
105### Use custom mirror
106To install from a remote mirror other than the default(https://releases.hashicorp.com/terraform). Use the `-m` or `--mirror` parameter.
107Ex: `tfswitch --mirror https://example.jfrog.io/artifactory/hashicorp`
108
109**Automatically switch with bash**
110
111Add the following to the end of your `~/.bashrc` file:
112(Use either `.tfswitchrc` or `.tfswitch.toml` or `.terraform-version`)
113
114```sh
115cdtfswitch(){
116  builtin cd "$@";
117  cdir=$PWD;
118  if [ -e "$cdir/.tfswitchrc" ]; then
119    tfswitch
120  fi
121}
122alias cd='cdtfswitch'
123```
124
125**Automatically switch with zsh**
126
127Add the following to the end of your `~/.zshrc` file:
128
129```sh
130load-tfswitch() {
131  local tfswitchrc_path=".tfswitchrc"
132
133  if [ -f "$tfswitchrc_path" ]; then
134    tfswitch
135  fi
136}
137add-zsh-hook chpwd load-tfswitch
138load-tfswitch
139```
140> NOTE: if you see an error like this: `command not found: add-zsh-hook`, then you might be on an older version of zsh (see below), or you simply need to load `add-zsh-hook` by adding this to your `.zshrc`:
141>    ```
142>    autoload -U add-zsh-hook
143>    ```
144
145*older version of zsh*
146```sh
147cd(){
148  builtin cd "$@";
149  cdir=$PWD;
150  if [ -e "$cdir/.tfswitchrc" ]; then
151    tfswitch
152  fi
153}
154```
155**Automatically switch with fish shell**
156
157Add the following to the end of your `~/.config/fish/config.fish` file:
158
159```sh
160function switch_terraform --on-event fish_postexec
161    string match --regex '^cd\s' "$argv" > /dev/null
162    set --local is_command_cd $status
163
164    if test $is_command_cd -eq 0
165      if count *.tf > /dev/null
166
167        grep -c "required_version" *.tf > /dev/null
168        set --local tf_contains_version $status
169
170        if test $tf_contains_version -eq 0
171            command tfswitch
172        end
173      end
174    end
175end
176```
177