Skip to content

Commit

Permalink
Simplify usage and docs (#175)
Browse files Browse the repository at this point in the history 
* Update docs terminology: ver-req

1. version requirements are what you set
2. versions are what you install
  • Loading branch information
@marcelklehr
marcelklehr authored Oct 18, 2016
1 parent 6d15df3 commit e7f7a58
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 66 deletions.
50 changes: 23 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,9 @@ cat "$NODIST_PREFIX/bin/nodist_bash_profile_content.sh" >> ~/.bash_profile
source ~/.bash_profile
```

### Activating nodist in PowerShell
You might need to 'Unblock' the file `bin\nodist.ps1` by right clicking on it in the Explorer and selecting that menu entry.

### Make it work in your IDE
If your IDE cannot access node or npm right away, don't fret! Find the relevant configuration settings and either set `path\to\Nodist\bin` as the Node installation dir or set `path\to\Nodist\bin\node.exe` as the path to the node binary directly.

Expand All @@ -58,13 +61,16 @@ Similar for npm: either set `...\Nodist\bin` as the installation path or `...\No
If you're looking to upgrade your Nodist installation, the easiest way is to uninstall (see below) the old installation and install the new version with the installer above.
You may need to reset your per-directory node version settings in order for them to work in v0.8 (ones set using nodist v0.6 should work fine, ones set using v0.7 will not).

#### Important usage changes in v0.8
Starting in v0.8 Nodist employs lazy version pattern evaluation. This means that setting versions per env/locally/globally doesn't set an explicit version, if you didn't give one. Instead the node.exe shim chooses a suitable version *at runtime*. Commands for installing a version and setting a requirement have been separated, thus, to update your node version (if your global version is set to `6`, e.g.), you now need to run `nodist + 6` (i.e. `nodist 6` doesn't do that for you anymore), which is probably how it should have worked all along.

#### Uninstall (v0.7)

1. Run the uninstaller either from the directory where you installed nodist, or from the Software Control Panel

2. Make sure to completely remove the nodist directory. (This will remove all your globally installed npm modules. If you don't want that, remove everything else, other than `nodist\bin\`.)

### Uninstall (<v0.7)
#### Uninstall (before v0.7)

1. Remove `<..path..>\nodist\bin` from your path. ([how?](http://www.computerhope.com/issues/ch000549.htm)).

Expand All @@ -76,18 +82,13 @@ You may need to reset your per-directory node version settings in order for them


## Usage
Nodist understands version patterns, like `0.12` or `4.x` or `~5` as well as `4.4.3` or `v4.4.3`.
As an added bonus, you may also use `latest`.

Nodist allows you to set version requirements for different scopes.
Version requirements can be fully specified versions, like `4.0.0` or patterns like `0.12`, `4.x`, `~5` or `latest`.
io.js is supported natively: Since node and io.js versions form a continuum you can simply use io.js versions as if they were node versions.

Btw, nodist also works in your PowerShell, but you might first need to 'Unblock' the file `bin\nodist.ps1`.

### Upgrading from < v0.8?
Starting in v0.8 Nodist employs lazy version pattern evaluation. This means that setting versions per env/locally/globally doesn't set an explicit version, if you didn't give one. Instead the node.exe shim chooses a suitable version *at runtime*. To update your node version (if your global version is set to `6`, e.g.), you now need to run `nodist + 6` (i.e. `nodist 6` doesn't do that for you anymore), which is probably how it should have worked all along.
Setting a requirement installs a matching version only if there is no other matching version already installed; otherwise existing installed versions will get referenced when executing `node.exe`.

### Scope precedence
Nodist allows you to set node and npm versions for different scopes. The following is a list of all scopes ordered by precedence (the first scope is the one with the highest priority; only if it's not set, the second scope is examined).
The following is a list of all scopes ordered by precedence (the first scope is the one with the highest priority; only if it's not set, the second scope is examined).

1. Environment (`NODIST_NODE_VERSION`and `NODIST_NPM_VERSION` env vars)
2. (optional:) Package (`package.json` with an `engines` field in the *directory of interest* or one of its parent directories)
Expand All @@ -109,37 +110,37 @@ Package.json inspection is turned off by default as of nodist v0.8.5. You can tu
```

```
> nodist 4.x
# Sets the global node version.
> nodist global 4.x
# Sets the global node version requirement
```

```
> nodist local 4.x
# Sets the node version per directory (including all subdirectories).
# Sets the node version requirement per directory (including all subdirectories).
```

```
> nodist env 4.x
# Sets the node version per terminal.
# Sets the node version requirement per terminal.
```

```
> nodist npm 3.x
# Globally activate npm 3
> nodist global npm 3.x
# Set global npm version requirement.
> nodist npm match
# Globally activates the npm version that corresponds to the active node version
# (the active node version may be the env, local or global version)
> nodist npm global match
# Tell nodist to always choose the npm version that matches the current node version.
# (the current node version may be determined by env, local or global requirements)
```

```
> nodist npm local 2.x
# Set the npm version for the current directory.
# Set the npm version requirement for the current directory.
```

```
> nodist npm env 2.x
# Set the npm version for the current terminal environment.
# Set the npm version requirement for the current terminal environment.
```

```
Expand All @@ -152,14 +153,9 @@ call nodist env 4.x
# Lists all available node versions.
```

```
> nodist r 4.x -- foo.js -s
# Runs a specific version without modifying any state.
```

```
> nodist + 4.x
# Just checks, if the version is installed and downloads it if not.
# Just checks, if the version is installed and installs it if not.
> nodist + all
# will install *everything*.
Expand Down
76 changes: 37 additions & 39 deletions usage.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,66 +9,64 @@ Usage:
nodist dist List all available node versions.
nodist ds

nodist add <version> Download the specified node version.
nodist + <version>
nodist add <version> Install the latest published version matching <version>;
nodist + <version> if any set requirement matches this version, this will get referenced in the future.

nodist rm <version> Uninstall the specified node version.
nodist - <version>
nodist rm <version> Uninstall the latest installed version matching <version>;
nodist - <version> if any set requirement matches this <version>, it will try to reference another installed version.

nodist <version> Use the specified node version globally
nodist global <version> (downloads the executable, if necessary).
nodist <ver-req> Set the global version requirement;
nodist global <ver-req> installs the specified node version if it hasn't been installed.

nodist local <version> Use <version> in this directory and its subdirectories.
(will add a ./node-version file)
nodist local <ver-req> Set the local requirement for this directory and its subdirectories;
adds or updates the ./node-version file.

nodist use <version> Use <version> in the current environment only
nodist env <version> (usually the current terminal window).
nodist env <ver-req> Set the requirement for the current environment only
(usually the current terminal window).

nodist run <version> -- <args..> Run <args> with the specified node version
nodist r <version> -- <args..> (downloads the executable, if necessary).
nodist run <ver-req> -- <args> Run <args> with a version matching the provided requirement
nodist r <ver-req> -- <args> (will abort if no matching version is installed).

nodist bin <version> Get the path to the specified node executable
(downloads the executable, if necessary).
nodist bin <ver-req> Get the path to the specified node <version>
(installs the node <version>, if necessary).

nodist path <version> Get the path to the specified node version directory
(downloads the executable, if necessary).
nodist path <ver-req> Get the path to the specified node <version> directory
(installs the node <version>, if necessary).

nodist npm <version> Activate the specified npm version
(downloads it if necessary)
nodist npm <ver-req> Set the global npm version requirement.
(installs the npm <version>, if necessary).

nodist npm match Activate the npm version matching the active
node version.
nodist npm match Activate the npm version matching the active node version
(active node version depends on env/local/global requirements).

nodist --help Display this help
nodist --help Display this help.

nodist -v Display nodist version
nodist -v Display nodist version.

Examples:

nodist 0.8.1 Use node v0.8.1 globally

nodist v0.5.10 Use node v0.5.10 globally

nodist - 0.5.10 Uninstall node v0.5.10
nodist 0.8.1 Sets the node global requirement to "0.8.1".
If 0.8.1 isn't already installed, nodist installs it.

nodist 5.x Sets the node global requirement to "5.x".
If there are no major versions of 5 installed, the last release is installed (5.12.0)

nodist latest Sets the node global requirement to the "latest" node version installed.
If a later version gets installed, the global requirement will match that version instead.

nodist r v0.8.1 -- foo.js -s Run `foo.js -s` with node v0.8.1, regardless
of the global version

nodist latest Use the latest available node version globally
(downloads the executable, if necessary).
nodist - 0.5.10 Uninstall node v0.5.10.

nodist + all Installs *all* available node versions.
(Get yourself a cuppa in the meantime...)
nodist + all Installs *all* available node versions
(Get yourself a cuppa in the meantime...).

Env vars:

NODIST_X64 Will always use the 64bit versions if set to '1'
NODIST_X64 Will always use the 64bit versions if set to '1'.

HTTP_PROXY Will use the Url and port specified as a proxy
(e.g. http://myproxy.com:8213 )
(e.g. http://myproxy.com:8213).

NODIST_NODE_MIRROR Set an alternative URL to fetch the node executables
from (e.g. http://mymirror.com/dist)
from (e.g. http://mymirror.com/dist).

NODIST_IOJS_MIRROR Set an alternative URL to fetch io.js exectuables
from.
NODIST_IOJS_MIRROR Set an alternative URL to fetch io.js exectuables from.

0 comments on commit e7f7a58

Please sign in to comment.