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.
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
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 | 🔴 | 🔴 | 🟢 |