alt the version switcher

alt is a command line utility that lets you switch between different versions of commands based on your current directory.

Why?

As developers, we work with a large number of tools. When we move from codebase to codebase, those tools and their versions change. Switching between the different versions of those tools every time you change codebase is a nightmare.

This is where alt comes in. It will automatically switch the version of commands when you move to a different codebase.

There are other tools out there that solve this problem. alt distinguish itself in a few ways:

• tool / language agnostic: Some version switching tools only work with a specific tool or programming language. alt is generic. It works for any command.
• no shell pollution: Most version switching tools hook themselves into your shell. This can slow down your shell's start time. alt does not hook into your shell. You can use it without slowing down your shell start time.
• only version switching: Unlike other tools, alt does not take responsibility for installing different versions of commands or managing their dependencies. How you install different versions of commands is entirely up to you.

Install

Debian / Ubuntu / Anything using DEBs

1. Open the latest release page on Github

2. Download the .deb file matching your system architecture

3. Install the .deb file by double clicking on it

4. OR Install the .deb file from the command line

   sudo apt install ./path/to/alt.deb

You will probably need to log out & log back in to your desktop session for alt to be configured.

OSX (Homebrew & Linuxbrew)

brew tap dotboris/alt
brew install alt

Pay close attention to the "Caveats" messages as you'll need to add a line to your ~/.bashrc / ~/.zshrc files.

Pre-packaged binaries

See: doc/install-pre-packaged-bins.md

From source

See: doc/install-from-source.md

Usage

Using alt is done in two steps:

1. First, you tell alt about the different versions of commands installed on your system.
2. Second, you tell alt what version of your commands to use in a given directory.

Define command versions

alt can automatically scan your system to find different version of a command. This can be done with the alt scan command:

alt scan some-command

This will bring up a menu that lets you choose all the versions of the given command that you want to use with alt.

• ↑ / ↓ or j / k: Move cursor
• Space: Make version available to alt
• Enter: Confirm and save selection

If alt is not able to find a version of a command automatically for you, you can always define the command version by hand.

This can be done with the alt def command:

alt def some-command version-name /path/to/command/bin

Switch command version

Remember that alt decides what version of a command to use based on the current directory. When you select a command version, it's for the current directory.

You can tell alt to use a specific version of a command in the current directory with the alt use command:

alt use some-command

This will bring up a menu that lets you choose the version of the specified command that you want to use.

• ↑ / ↓ or j / k: Move cursor
• Enter: Select version to use

If menus aren't your cup of tea, you can specify the version on the command line:

alt use some-command version-name

Note: If you want to use the system version without the menu, you can pass system as the version-name.

alt use some-command system

Show known commands & used versions

alt show

The above command will show you:

• All commands alt knows about
• The versions of those commands available
• The versions being used in the current directory

Troubleshooting

If you are experiencing issues with alt, you should try running alt's built-in self-healing command:

alt doctor

This command will look for problems, report them to you and, in some cases, propose an automatic fix.

If alt doctor is not able to find or fix your problem, you can try looking at the sections below. If that doesn't help, feel free to open an issue. We'll be happy to help you out.

Warning about shims directory not being in PATH

Behind the scenes, alt manages a directory of "shims" ($HOME/.local/alt/shims). In order to switch the version of commands, it needs that directory to be at the top of your PATH environment variable.

During the install process, we install scripts that configure this automatically for you. These scripts are /etc/profile.d/alt.sh & /etc/fish/conf.d/alt.fish (the location of these scripts may vary on some platforms).

In some cases, you may need to force these scripts to re-load. You can try the following steps:

1. Close & re-open your terminal
2. Log out of your desktop session & log back in again

If either or both of these fail, you can put the shim directory on top of your PATH manually. This will vary depending on what shell you use.

# For BASH
echo 'export PATH="$HOME/.local/alt/shims:$PATH"' >> ~/.bashrc

# For ZSH
echo 'export PATH="$HOME/.local/alt/shims:$PATH"' >> ~/.zshrc

# For FISH
echo 'set -gx PATH "$HOME/.local/alt/shims" $PATH' >> ~/.config/fish/config.fish

.alt.toml file in git repositories

During it's normal operation, alt puts a file named .alt.toml in the current directory. You should not commit .alt.toml to git or any other VCS. To avoid getting those files all over your git repositories, you can add them to a global gitignore file.

If you don't know how to create a global gitignore file, see: https://help.github.com/articles/ignoring-files/#create-a-global-gitignore

echo '.alt.toml' >> path/to/your/global-gitgnore