Quick Start

Here we take Nodejs as an example to introduce how to use vfox.

1. Installation

Windows

Scoop

scoop install vfox

winget

winget install vfox

Setup Installer

Please go to the Releases page to download the latest version of the setup installer, and then follow the installation wizard to install.

Manual Installation

1. Download the latest version of the zip installer from Releases
2. Configure the PATH environment variable to add the vfox installation directory to the PATH environment variable.

Unix-like

Homebrew

$ brew install vfox

APT

 echo "deb [trusted=yes] https://apt.fury.io/versionfox/ /" | sudo tee /etc/apt/sources.list.d/versionfox.list
 sudo apt-get update
 sudo apt-get install vfox

YUM

echo '[vfox]
name=VersionFox Repo
baseurl=https://yum.fury.io/versionfox/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/versionfox.repo

sudo yum install vfox

Manual Installation

$ curl -sSL https://raw.githubusercontent.com/version-fox/vfox/main/install.sh | bash

2. Hook vfox to your Shell

WARNING

Please select a command suitable for your Shell from below to execute!

Bash

echo 'eval "$(vfox activate bash)"' >> ~/.bashrc

ZSH

echo 'eval "$(vfox activate zsh)"' >> ~/.zshrc

Fish

echo 'vfox activate fish | source' >> ~/.config/fish/config.fish

Powershell

Open PowerShell Profile:

New-Item -Type File -Path $PROFILE # Just ignore the 'file already exists' error.

# If it prompts "Unable to find the path", then you need to forcefully create profile. Add the "-Force" option.
# New-Item -Type File -Path $PROFILE –Force

Invoke-Item $PROFILE  # open Profile

Add the following line to the end of your profile and save:

Invoke-Expression "$(vfox activate pwsh)"

Clink & Cmder

1. Find the scripts path:

   clink info | findstr scripts

2. Copy clink_vfox.lua to the scripts directory
3. Restart Clink or Cmder

3. Add a plugin

Command: vfox add <plugin-name>

After you have installed vfox, you still can't do anything. You need to install the corresponding plugin first.

TIP

If you don't know which plugin to add, you can use the vfox available command to see all available plugins.

$ vfox add nodejs

4. Install a runtime

After the plugin is successfully installed, you can install the corresponding version of Nodejs.

Command: vfox install nodejs@<version>

We only install the latest available latest version:

$ vfox install nodejs@latest

Of course, we can also install a specific version:

$ vfox install nodejs@21.5.0

WARNING

vfox forces the use of an exact version. latest is a behavior that is parsed to the actual version number at runtime, depending on the plugin's implementation.

If you **don't know the specific version **, you can use vfox search nodejs to see all available versions.

TIP

install and search commands will check if the plugin is already added locally. If not, they will automatically add the plugin.

5. Switch runtime

Command: vfox use [-p -g -s] nodejs[@<version>]

vfox supports three scopes, each with a different range of effects:

Global

It takes effect globally

$ vfox use -g nodejs

TIP

Global is managed in the $HOME/.version-fox/.tool-versions file.

The contents of the .tool-versions file as follows:

nodejs 21.5.0

Does not take effect after execution?

Please check if there is a runtime installed previously through other means in the $PATH!

For Windows users:

1. Please ensure that the system environment variable Path does not contain the runtime installed previously through other means!

2. vfox will automatically add the installed runtime to the user environment variable Path.

3. If there is a runtime installed previously through other means in your Path, please remove it manually!

Project

Different versions for different projects

$ vfox use -p nodejs

vfox will automatically detect whether there is a .tool-versions file in the directory when you enter a directory. If it exists, vfox will automatically switch to the version specified by the project.

TIP

Project is managed in the $PWD/.tool-versions file (current working directory).

Default scope

If you do not specify a scope, vfox will use the default scope. Different systems have different scopes:

For Windows: The default scope is Global

For Unix-like: The default scope is Session

Session

Different versions for different Shells

$ vfox use -s nodejs

The session scope takes effect only for the current shell session. In other words, the versions are not shared between.

The main purpose of this scope is to meet temporary needs. When you close the current terminal, vfox will automatically switch back to the Global/Project version.

TIP

Session is managed in the $HOME/.version-fox/tmp/<shell-pid>/.tool-versions file (temporary directory).

Demo

TIP

Sometimes, text expressions are far less intuitive than pictures, so let's go directly to the effect picture!

Guide Complete!

That completes the Getting Started guide for vfox🎉 You can now manage nodejs versions for your project. Follow similar steps for each type of tool in your project!

vfox has many more commands to become familiar with, you can see them all by running vfox --help or vfox.