Workflows

With proto, we provide multiple workflows for everyday use for you to choose from. They can be used individually, or together, it's up to you!

Shims

proto is primarily powered by the industry standard concept of shims. For each tool installed in proto, a shim file will exist at ~/.proto/shims for the primary executable, and some secondary executables. Shims are not symlinks to the tool's binary, but are thin wrappers around proto run, enabling runtime version detection on every invocation! For example, these are equivalent:

$ proto run node -- --version
20.0.0

$ node --version
20.0.0

$ which node
~/.proto/shims/node

Setup

To make use of shims, prepend the ~/.proto/shims directory to PATH in your shell profile. This must come before the bin directory if using both.

If you're using or plan to use shell activation, this happens automatically and can be ignored.

Binary linking

Alternatively, we also support a non-shim based approach, which creates symlinks to a versioned tool's primary and secondary executables. For each tool installed in proto, a symlink will exist at ~/.proto/bin for the globally pinned version (configured in ~/.proto/.prototools).

$ node --version
20.0.0

$ which node
~/.proto/bin/node -> ~/.proto/tools/node/20.0.0/bin/node

The version of a tool that's symlinked is not dynamic and is manually linked by pinning the chosen version with proto install --pin=global or proto pin --global. This also happens automatically the first time a tool is installed.

warning

Not all tools support symlinking a binary, as not all files are executable. For example, most Node.js package managers currently do not support this, as JavaScript files are not executable (especially on Windows). Shims are required for these tools.

Setup

To make use of bins, prepend the ~/.proto/bin directory to PATH in your shell profile. This must come after the shim directory if using both.

If you're using or plan to use shell activation, this happens automatically and can be ignored.

Shell activationv0.38.0

danger

This feature is extremely experimental and may change based on feedback! If you run into any issues, please report an issue on GitHub or Discord.

Our last workflow is what we call shell activation (or shell hooks), and it's where the proto environment is setup/reset every time you change directories. If you're coming from another version manager, you may be familiar with this kind of workflow.

So how does this work exactly? In your shell profile, you'll evaluate a call to proto activate <shell>, which generates a bunch of shell specific syntax that registers a hook for "run this code when the current directory or prompt line changes". Once this hook is registered and you run cd (for example), proto will...

• Load all .prototools files
• Extract tools with a configured version
• For each tool:
  • Load associated WASM plugin
  • Export environment variables based on [env] and [tools.*.env]
  • Prepend PATH with tool-specific directories (like local and global executables) for the detected version

$ cd /some/path && node --version
20.0.0

$ cd /another/path && node --version
18.0.0

Setup

View the proto activate documentation for information on how to setup your shell profile for this workflow.

Comparison

The workflows above may come across as information overload, so we've provided the following comparison table outlining the features each workflow supports.

	Shims	Bins	Activate
Runtime version detection	🟢	🔴	🟠 only when the hook triggers
Supports multiple versions	🟢	🔴	🟢
Fixed to a single version	🟠 with arg or env var	🟢	🟠 if not using shims
Includes all tool executables	🔴	🔴	🟢
Includes tool globals/packages	🔴	🔴	🟢
Exports environment variables	🔴	🔴	🟢
Prepends PATH	🔴	🔴	🟢
Can pin proto's version	🔴	🔴	🟢