asdf/docs/core-configuration.md

## .tool-versions

Whenever `.tool-versions` file is present in a directory, the tool versions it declares will be used in that directory and any subdirectories.

?> Global defaults can be set in the file `$HOME/.tool-versions`

This is what a `.tool-versions` file looks like:

```
ruby 2.5.3
nodejs 10.15.0
```

The versions can be in the following format:

- `10.15.0` - an actual version. Plugins that support downloading binaries, will download binaries.
- `ref:v1.0.2-a` or `ref:39cb398vb39` - tag/commit/branch to download from github and compile
- `path:/src/elixir` - a path to custom compiled version of a tool to use. For use by language developers and such.
- `system` - this keyword causes asdf to passthrough to the version of the tool on the system that is not managed by asdf.

Multiple versions can be set by separating them with a space. For example, to use
Python 3.7.2, fallback to Python 2.7.15 and finally to the system Python, the
following line can be added to `.tool-versions`.

```
python 3.7.2 2.7.15 system
```

To install all the tools defined in a `.tool-versions` file run `asdf install` with no other arguments in the directory containing the `.tool-versions` file.

Edit the file directly or use `asdf local` (or `asdf global`) which updates it.

## \$HOME/.asdfrc

Add a `.asdfrc` file to your home directory and asdf will use the settings specified in the file. The file should be formatted like this:

```
legacy_version_file = yes
```

**Settings**

- `legacy_version_file` - defaults to `no`. If set to yes it will cause plugins that support this feature to read the version files used by other version managers (e.g. `.ruby-version` in the case of Ruby's `rbenv`).
- `use_release_candidates` - defaults to `no`. If set to yes it will cause the `asdf update` command to upgrade to the latest release candidate release instead of the latest semantic version.
- `always_keep_download` - defaults to `no`. If set to `yes` it will cause `asdf install` always keep the source code or binary it downloads. If set to `no` the source code or binary downloaded by `asdf install` will be deleted after successful installation.

## Environment Variables

- `ASDF_CONFIG_FILE` - Defaults to `~/.asdfrc` as described above. Can be set to any location.
- `ASDF_DEFAULT_TOOL_VERSIONS_FILENAME` - The name of the file storing the tool names and versions. Defaults to `.tool-versions`. Can be any valid file name.
- `ASDF_DATA_DIR` - Defaults to `~/.asdf` - Location where `asdf` install plugins, shims and installs. Can be set to any location before sourcing `asdf.sh` or `asdf.fish` mentioned in the section above.
Documentation site (#422) * init docsify * add config & plugins to support required features * create cover page * add sidebar headings * add novel 404 page * add translation message to 404 * add navbar with translations dropdown * fix punctuation * add all-plugins section pulling from asdf-plugins repo readme * update sidebar with sections, better names & descriptions for contributors * add changelog. pulls from repo * add thanks page. credits, maintainers & link to contributors on github * add core documentation * rm old readme from docs/ folder this was copied here on docsify init * comment out some translation config ideally this will remain commented out serving as an example for any translation contributions * run prettier over markdown * add plugins-create section * add contributing sections to the docs * fix cover page get-started link * use the readme as the main homepage * update asdf version in docs with release script 2019-01-12 09:32:30 -07:00			`## .tool-versions`

Significant documentation site improvements (#440) # Summary This contains fixes and significant improvements to the documentation site. * fixes some routing issues due to erroneous docsify config * fixed links and layout of 404 pg * improved the language on the landing page as per #438 * propose a NEW_README.md tackling concerns with #438 and #422 * use docsify specific md to emphasise some text * add docsify-themeable plugin to improve loading experience and future proof for customisation * improve use of `asdf-vm` over `asdf` ## Other Information Included in this PR is a file `docs/NEW_README.md` which is my proposed README for this repo. The intention was to have all documentation in a single place, the site, and simplify the readme bringing the focus to explaining the tool rather than instructing users on how to use it. I will create a separate PR for the README, but in the meantime the landing page composes this new readme with the ballad. 2019-01-25 01:17:20 -07:00			Whenever `.tool-versions` file is present in a directory, the tool versions it declares will be used in that directory and any subdirectories.

			?> Global defaults can be set in the file `$HOME/.tool-versions`
Documentation site (#422) * init docsify * add config & plugins to support required features * create cover page * add sidebar headings * add novel 404 page * add translation message to 404 * add navbar with translations dropdown * fix punctuation * add all-plugins section pulling from asdf-plugins repo readme * update sidebar with sections, better names & descriptions for contributors * add changelog. pulls from repo * add thanks page. credits, maintainers & link to contributors on github * add core documentation * rm old readme from docs/ folder this was copied here on docsify init * comment out some translation config ideally this will remain commented out serving as an example for any translation contributions * run prettier over markdown * add plugins-create section * add contributing sections to the docs * fix cover page get-started link * use the readme as the main homepage * update asdf version in docs with release script 2019-01-12 09:32:30 -07:00
			This is what a `.tool-versions` file looks like:

			```
			`ruby 2.5.3`
			`nodejs 10.15.0`
			```

			`The versions can be in the following format:`

			- `10.15.0` - an actual version. Plugins that support downloading binaries, will download binaries.
			- `ref:v1.0.2-a` or `ref:39cb398vb39` - tag/commit/branch to download from github and compile
			- `path:/src/elixir` - a path to custom compiled version of a tool to use. For use by language developers and such.
			- `system` - this keyword causes asdf to passthrough to the version of the tool on the system that is not managed by asdf.

Add documentation about multiple versions 2019-03-14 13:49:49 -07:00			`Multiple versions can be set by separating them with a space. For example, to use`
			`Python 3.7.2, fallback to Python 2.7.15 and finally to the system Python, the`
			following line can be added to `.tool-versions`.

			```
			`python 3.7.2 2.7.15 system`
			```

Documentation site (#422) * init docsify * add config & plugins to support required features * create cover page * add sidebar headings * add novel 404 page * add translation message to 404 * add navbar with translations dropdown * fix punctuation * add all-plugins section pulling from asdf-plugins repo readme * update sidebar with sections, better names & descriptions for contributors * add changelog. pulls from repo * add thanks page. credits, maintainers & link to contributors on github * add core documentation * rm old readme from docs/ folder this was copied here on docsify init * comment out some translation config ideally this will remain commented out serving as an example for any translation contributions * run prettier over markdown * add plugins-create section * add contributing sections to the docs * fix cover page get-started link * use the readme as the main homepage * update asdf version in docs with release script 2019-01-12 09:32:30 -07:00			To install all the tools defined in a `.tool-versions` file run `asdf install` with no other arguments in the directory containing the `.tool-versions` file.

			Edit the file directly or use `asdf local` (or `asdf global`) which updates it.

			`## \$HOME/.asdfrc`

			Add a `.asdfrc` file to your home directory and asdf will use the settings specified in the file. The file should be formatted like this:

			```
			`legacy_version_file = yes`
			```

			`Settings`

			- `legacy_version_file` - defaults to `no`. If set to yes it will cause plugins that support this feature to read the version files used by other version managers (e.g. `.ruby-version` in the case of Ruby's `rbenv`).
Add support for RC versions to asdf update command 2019-03-24 15:24:19 -07:00			- `use_release_candidates` - defaults to `no`. If set to yes it will cause the `asdf update` command to upgrade to the latest release candidate release instead of the latest semantic version.
Add documentation on always_keep_download configuration option 2020-03-02 08:32:00 -07:00			- `always_keep_download` - defaults to `no`. If set to `yes` it will cause `asdf install` always keep the source code or binary it downloads. If set to `no` the source code or binary downloaded by `asdf install` will be deleted after successful installation.
Documentation site (#422) * init docsify * add config & plugins to support required features * create cover page * add sidebar headings * add novel 404 page * add translation message to 404 * add navbar with translations dropdown * fix punctuation * add all-plugins section pulling from asdf-plugins repo readme * update sidebar with sections, better names & descriptions for contributors * add changelog. pulls from repo * add thanks page. credits, maintainers & link to contributors on github * add core documentation * rm old readme from docs/ folder this was copied here on docsify init * comment out some translation config ideally this will remain commented out serving as an example for any translation contributions * run prettier over markdown * add plugins-create section * add contributing sections to the docs * fix cover page get-started link * use the readme as the main homepage * update asdf version in docs with release script 2019-01-12 09:32:30 -07:00
			`## Environment Variables`

			- `ASDF_CONFIG_FILE` - Defaults to `~/.asdfrc` as described above. Can be set to any location.
			- `ASDF_DEFAULT_TOOL_VERSIONS_FILENAME` - The name of the file storing the tool names and versions. Defaults to `.tool-versions`. Can be any valid file name.
			- `ASDF_DATA_DIR` - Defaults to `~/.asdf` - Location where `asdf` install plugins, shims and installs. Can be set to any location before sourcing `asdf.sh` or `asdf.fish` mentioned in the section above.