kevin/asdf
1
Fork 0
mirror of https://github.com/asdf-vm/asdf.git synced 2024-11-15 01:28:17 -07:00
Code Issues Packages Projects Releases Wiki Activity

Documentation install section update (#699)

Browse Source
This commit is contained in:
James Hegedus 2020-04-21 11:34:45 +10:00 committed by GitHub
parent 90b1e5d816
commit 678b3efc35
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 199 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

288
docs/core-manage-asdf-vm.md
View File

@ -1,8 +1,9 @@
## Install asdf-vm
<!-- tabs:start -->
<!-- select:start -->
<!-- select-menu-labels: Installation Method -->
#### ** Git **
### --Git--
Clone only the latest branch:
@ -18,9 +19,9 @@ cd ~/.asdf
git checkout "$(git describe --abbrev=0 --tags)"
```
#### ** Homebrew **
### --Homebrew--
Install using the Homebrew package manager on macOS:
Install using the Homebrew package manager:
```shell
brew install asdf
@ -32,136 +33,180 @@ To use the latest changes, you can point Homebrew to the master branch of the re
brew install asdf --HEAD
```
<!-- tabs:end -->
<!-- select:end -->
### Add to your Shell
<!-- tabs:start -->
<!-- select:start -->
<!-- select-menu-labels: Operating System,Shell,Installation Method -->
#### ** Bash on Linux **
#### --Linux,Bash,Git--
```bash
echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bashrc
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc
```
#### ** Bash on macOS **
Installation via **Git**:
```bash
echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bash_profile
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bash_profile
```
Note if you are using Catalina or newer, the default shell has changed to Zsh:
```bash
echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.zprofile
```
Installation via **Homebrew**:
?> If you have Homebrew's Bash completions configured, the second line below is
unnecessary. See [Configuring Completions
in Bash](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash)
in the Homebrew docs.
```bash
echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.bash_profile
echo -e "\n. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash" >> ~/.bash_profile
```
#### ** ZSH **
Installation via **Git**:
Source the `asdf.sh` script in your shell config:
Add the following to `~/.bashrc`:
```shell
echo -e "\n. $HOME/.asdf/asdf.sh" >> ~/.zshrc
. $HOME/.asdf/asdf.sh
```
or use a framework plugin like [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) which will source this init script and setup completions.
ZSH Completions:
asdf ships with ZSH completions which will need to be setup if you're not using a ZSH framework plugin that does this for you. Add the following to your `.zshrc`:
?> Completions must be configured by adding the following to your `.bashrc`:
```shell
# append completions to fpath
echo -e "\nfpath=(${ASDF_DIR}/completions $fpath)" >> ~/.zshrc
# initialise completions with ZSH's compinit
echo -e "\nautoload -Uz compinit && compinit" >> ~/.zshrc
. $HOME/.asdf/completions/asdf.bash
```
- if you are using a custom `compinit` setup, ensure `compinit` is below your sourcing of `asdf.sh`
- if you are using a custom `compinit` setup with a ZSH framework, ensure `compinit` is below your sourcing of the framework
- if you are using a ZSH framework with an asdf plugin, then you shouldn't need to manually add `fpath`, the plugin may need to be updated to use the new ZSH completions properly
#### --Linux,Fish,Git--
Installation via **Homebrew**:
Add the following to `~/.config/fish/config.fish`:
```shell
echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.zshrc
source ~/.asdf/asdf.fish
```
Shell completions should automatically be installed and available.
#### ** Fish **
Installation via **Git**:
?> Completions must be configured manually with the following command:
```shell
echo 'source ~/.asdf/asdf.fish' >> ~/.config/fish/config.fish
mkdir -p ~/.config/fish/completions; and cp ~/.asdf/completions/asdf.fish ~/.config/fish/completions
```
Installation via **Homebrew**:
#### --Linux,ZSH,Git--
?> Homebrew takes care of [installing the completions for fish
shell](https://docs.brew.sh/Shell-Completion#configuring-completions-in-fish).
Friendly!
Add the following to `~/.zshrc`:
```shell
echo "source "(brew --prefix asdf)"/asdf.fish" >> ~/.config/fish/config.fish
. $HOME/.asdf/asdf.sh
```
<!-- tabs:end -->
**OR** use a ZSH Framework plugin like [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) which will source this script and setup completions.
?> Completions are configured by either a ZSH Framework `asdf` plugin or by adding the following to your `.zshrc`:
```shell
# append completions to fpath
fpath=(${ASDF_DIR}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit
compinit
```
- if you are using a custom `compinit` setup, ensure `compinit` is below your sourcing of `asdf.sh`
- if you are using a custom `compinit` setup with a ZSH Framework, ensure `compinit` is below your sourcing of the framework
!> if you are using a ZSH Framework the associated `asdf` plugin may need to be updated to use the new ZSH completions properly via `fpath`. The Oh-My-ZSH asdf plugin is yet to be updated, see https://github.com/ohmyzsh/ohmyzsh/pull/8837.
#### --macOS,Bash,Git--
If using **macOS Catalina or newer**, the default shell has changed to **ZSH**. Unless changing back to Bash, follow the ZSH instructions.
Add the following to `~/.bash_profile`:
```shell
. $HOME/.asdf/asdf.sh
```
?> Completions must be configured manually with the following entry in your `.bash_profile`:
```shell
. $HOME/.asdf/completions/asdf.bash
```
#### --macOS,Fish,Git--
Add the following to `~/.config/fish/config.fish`:
```shell
source ~/.asdf/asdf.fish
```
?> Completions must be configured manually with the following command:
```shell
mkdir -p ~/.config/fish/completions; and cp ~/.asdf/completions/asdf.fish ~/.config/fish/completions
```
#### --macOS,ZSH,Git--
Add the following to `~/.zshrc`:
```shell
. $HOME/.asdf/asdf.sh
```
**OR** use a ZSH Framework plugin like [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) which will source this script and setup completions.
?> Completions are configured by either a ZSH Framework `asdf` plugin or by adding the following to your `.zshrc`:
```shell
# append completions to fpath
fpath=(${ASDF_DIR}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit
compinit
```
- if you are using a custom `compinit` setup, ensure `compinit` is below your sourcing of `asdf.sh`
- if you are using a custom `compinit` setup with a ZSH Framework, ensure `compinit` is below your sourcing of the framework
!> if you are using a ZSH Framework the associated `asdf` plugin may need to be updated to use the new ZSH completions properly via `fpath`. The Oh-My-ZSH asdf plugin is yet to be updated, see https://github.com/ohmyzsh/ohmyzsh/pull/8837.
#### --macOS,Bash,Homebrew--
If using **macOS Catalina or newer**, the default shell has changed to **ZSH**. Unless changing back to Bash, follow the ZSH instructions.
Add the following to `~/.bash_profile`:
```shell
. $(brew --prefix asdf)/asdf.sh
```
?> Completions will need to be [configured as per Homebrew's instructions](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) or with the following:
```shell
echo -e "\n. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash" >> ~/.bash_profile
```
#### --macOS,Fish,Homebrew--
Add the following to `~/.config/fish/config.fish`:
```shell
source "(brew --prefix asdf)"/asdf.fish
```
?> Completions are [handled by Homebrew for the Fish shell](https://docs.brew.sh/Shell-Completion#configuring-completions-in-fish). Friendly!
#### --macOS,ZSH,Homebrew--
Add the following to `~/.zshrc`:
```shell
. $(brew --prefix asdf)/asdf.sh
```
?> Completions will need to be [configured as per Homebrew's instructions](https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh).
### --Docsify Select Default--
!> The `Homebrew` `asdf` Formulae has not been tested on `Linux` by the core asdf team. Please raise an issue if this has changed and we will update the docs.
<!-- select:end -->
Restart your shell so that PATH changes take effect. (Opening a new terminal
tab will usually do it.)
You are ready to use asdf 🎉
### Having Issues?
!> If you're having issues with it not detecting the shims you've installed it's most-likely due to the sourcing of above `asdf.bash` or `asdf.fish` not being at the **BOTTOM** of your `~/.bash_profile`, `~/.zshrc`, or `~/.config/fish/config.fish`. It needs to be sourced **AFTER** you have set your `$PATH.` and **AFTER** you have sourced your framework (oh-my-zsh etc).
If you're having issues with your shell not detecting newly installed shims, it's most-likely due to the sourcing of `asdf.sh` or `asdf.fish` not being at the **BOTTOM** of your `.bash_profile`, `.zshrc`, `config.fish` config file. It needs to be sourced **AFTER** you have set your `$PATH` and **AFTER** you have sourced your framework (oh-my-zsh etc).
### Plugin Dependencies
?> For most plugins, it is good if you have installed the following packages OR their equivalent on your OS
For most plugins, it is good if you have installed the following packages:
<!-- tabs:start -->
<!-- select:start -->
<!-- select-menu-labels: Operating System,Installation Method -->
#### ** macOS **
Installation via Homebrew:
```shell
brew install \
coreutils automake autoconf openssl \
libyaml readline libxslt libtool unixodbc \
unzip curl
```
Installation via Spack:
```shell
spack install \
coreutils automake autoconf openssl \
libyaml readline libxslt libtool unixodbc \
unzip curl
```
#### ** Ubuntu **
#### -- Linux,Aptitude --
```shell
sudo apt install \
@ -171,7 +216,7 @@ sudo apt install \
unzip curl
```
#### **Fedora**
#### -- Linux,DNF --
```shell
sudo dnf install \
@ -181,17 +226,40 @@ sudo dnf install \
unzip curl
```
<!-- tabs:end -->
#### -- macOS,Homebrew --
That's all! You are ready to use asdf 🎉
```shell
brew install \
coreutils automake autoconf openssl \
libyaml readline libxslt libtool unixodbc \
unzip curl
```
?> If you're migrating from other tools and want to use your existing `.node-version` or `.ruby-version` version files, look at the [`legacy_version_file` flag in the configuration section](core-configuration?id=homeasdfrc).
#### -- macOS,Spack --
```shell
spack install \
coreutils automake autoconf openssl \
libyaml readline libxslt libtool unixodbc \
unzip curl
```
### -- Docsify Select Default --
No match for _Operating System_ and _Installation Method_ selections. Please try another combination.
<!-- select:end -->
### Migrating Tools
If you're migrating from other tools and want to use your existing version files (eg: `.node-version` or `.ruby-version`), look at the `legacy_version_file` [flag in the configuration section](core-configuration?id=homeasdfrc).
## Update
<!-- tabs:start -->
<!-- select:start -->
<!-- select-menu-labels: Installation Method -->
### ** Git **
### -- Git --
```shell
asdf update
@ -203,19 +271,19 @@ If you want the latest changes that aren't yet included in a stable release:
asdf update --head
```
### ** Homebrew **
### -- Homebrew --
```shell
brew upgrade asdf
```
<!-- tabs:end -->
<!-- select:end -->
## Remove
Uninstalling `asdf` is as simple as:
1. In your `.bashrc` (or `.bash_profile` if you are on OSX) or `.zshrc` find the lines that source `asdf.sh` and the autocompletions. The lines should look something like this:
1. In your `.bashrc`/`.bash_profile`/`.zshrc`/`config.fish` find the lines that source `asdf.sh` and the completions (this may be a ZSH Framework plugin). In Bash, the lines look something like this:
```shell
. $HOME/.asdf/asdf.sh
@ -224,10 +292,14 @@ Uninstalling `asdf` is as simple as:
Remove these lines and save the file.
2. Run `rm -rf ~/.asdf/ ~/.tool-versions` to completely remove all the asdf
files from your system.
2. Run
3. _(Optional)_ If you installed asdf using a package manager, you may want to use
that package manager to uninstall the core asdf files.
```shell
rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} ~/.tool-versions
```
to completely remove all the asdf files from your system.
3. _(Optional)_ If you installed asdf using a package manager, you may want to use that package manager to uninstall the core asdf files.
That's it! 🎉

25
docs/index.html
View File

@ -47,6 +47,14 @@
},
themeColor: "#AA00D4",
formatUpdated: "{MM}/{DD} {HH}:{mm}",
select: {
detectOperatingSystem: {
enabled: true,
menuId: "operating-system",
},
sync: true,
theme: "classic",
},
tabs: {
theme: "material",
},
@ -61,12 +69,16 @@
},
plugins: [
EditOnGithubPlugin.create(
"https://github.com/asdf-vm/asdf/blob/master/docs/", {
customURLs: {
"https://raw.githubusercontent.com/asdf-vm/asdf-plugins/master/README.md": "https://github.com/asdf-vm/asdf-plugins/edit/master/README.md",
"https://raw.githubusercontent.com/asdf-vm/asdf/master/CHANGELOG.md": "https://github.com/asdf-vm/asdf/edit/master/CHANGELOG.md"
"https://github.com/asdf-vm/asdf/blob/master/docs/",
{
customURLs: {
"https://raw.githubusercontent.com/asdf-vm/asdf-plugins/master/README.md":
"https://github.com/asdf-vm/asdf-plugins/edit/master/README.md",
"https://raw.githubusercontent.com/asdf-vm/asdf/master/CHANGELOG.md":
"https://github.com/asdf-vm/asdf/edit/master/CHANGELOG.md",
},
}
})
),
],
};
</script>
@ -77,6 +89,7 @@
<script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
<script src="//unpkg.com/docsify/lib/plugins/zoom-image.min.js"></script>
<!-- 3rd party plugins -->
<script src="https://cdn.jsdelivr.net/npm/docsify-select@1"></script>
<script src="//unpkg.com/docsify-themeable@0"></script>
<script src="//unpkg.com/docsify-copy-code@2"></script>
<script src="//unpkg.com/docsify-tabs@1"></script>
@ -85,7 +98,7 @@
<style>
:root {
/* Reduce the font size */
--base-font-size: 14px;
/* --base-font-size: 14px; */
/* Change the theme color hue */
--theme-color: #aa00d4;