From eb978e81b8024d471857624e668ca9537a41938c Mon Sep 17 00:00:00 2001 From: Miles Johnson Date: Fri, 6 Sep 2024 17:46:22 -0700 Subject: [PATCH] docs: Add proto v0.41 docs. (#1646) * Update commands. * Add offline settings. --- website/docs/proto/commands/alias.mdx | 15 +++-- website/docs/proto/commands/install.mdx | 3 + website/docs/proto/commands/pin.mdx | 20 +++--- website/docs/proto/commands/plugin/add.mdx | 8 ++- website/docs/proto/commands/plugin/remove.mdx | 7 +- website/docs/proto/commands/unalias.mdx | 15 +++-- website/docs/proto/commands/unpin.mdx | 16 ++--- website/docs/proto/config.mdx | 64 ++++++++++++++++++- 8 files changed, 107 insertions(+), 41 deletions(-) diff --git a/website/docs/proto/commands/alias.mdx b/website/docs/proto/commands/alias.mdx index e4c9baf3d0a..7caad8df84c 100644 --- a/website/docs/proto/commands/alias.mdx +++ b/website/docs/proto/commands/alias.mdx @@ -2,6 +2,8 @@ title: alias --- +import VersionLabel from '@site/src/components/Docs/VersionLabel'; + The `proto alias ` (or `proto a`) command will define a custom alias that maps to a specific version for the provided tool. Aliases can be used anywhere a version is accepted. @@ -10,12 +12,8 @@ accepted. $ proto alias node work 16.16 ``` -By default this will update the local [`./.prototools`](../config) file. Pass `--global` to update -the global [`~/.proto/.prototools`](../config) file instead. - -```shell -$ proto alias yarn berry 4 --global -``` +By default this will update the local [`./.prototools`](../config) file. Pass `--to` to customize +the location. ### Arguments @@ -25,4 +23,7 @@ $ proto alias yarn berry 4 --global ## Options -- `--global` - Pin to the global `~/.proto/.prototools` instead of the local `./.prototools`. +- `--global` (deprecated) - Pin to the global `~/.proto/.prototools` instead of the local + `./.prototools`. +- `--to` - [Location of `.prototools`](../config#locations) to update. + diff --git a/website/docs/proto/commands/install.mdx b/website/docs/proto/commands/install.mdx index f097e0195d9..7343f17b3a4 100644 --- a/website/docs/proto/commands/install.mdx +++ b/website/docs/proto/commands/install.mdx @@ -50,6 +50,9 @@ $ proto install bun --pin local # ~/.proto/.prototools $ proto install bun --pin global + +# ~/.prototools +$ proto install bun --pin user ``` ### Handling plugin hooks diff --git a/website/docs/proto/commands/pin.mdx b/website/docs/proto/commands/pin.mdx index faf01be2dda..0c8e7abcf4b 100644 --- a/website/docs/proto/commands/pin.mdx +++ b/website/docs/proto/commands/pin.mdx @@ -6,22 +6,15 @@ import VersionLabel from '@site/src/components/Docs/VersionLabel'; -The `proto pin ` command will pin a version (or alias) of a tool. By default it will -pin to a `./.prototools` file in the current directory. This version will be used when attempting to -[detect a version](../detection). +The `proto pin ` command will pin a version (or alias) of a tool. This version will +be used when attempting to [detect a version](../detection). ```shell $ proto pin go 1.20 ``` -When the `--global` option is passed, the version will be pinned globally in `~/.proto/.prototools`. -This version will be used as a global fallback when attempting to [detect a version](../detection). - -```shell -$ proto pin go 1.20 --global -``` - -> [Learn more about the `.prototools` configuration file!](../config) +By default this will update the local [`./.prototools`](../config) file. Pass `--to` to customize +the location. ### Arguments @@ -30,5 +23,8 @@ $ proto pin go 1.20 --global ### Options -- `--global` - Pin to the global `~/.proto/.prototools` instead of the local `./.prototools`. +- `--global` (deprecated) - Pin to the global `~/.proto/.prototools` instead of the local + `./.prototools`. - `--resolve` - Resolve the version to a fully-qualified semantic version before pinning. +- `--to` - [Location of `.prototools`](../config#locations) to update. + diff --git a/website/docs/proto/commands/plugin/add.mdx b/website/docs/proto/commands/plugin/add.mdx index e48cde271a9..64196e60c4f 100644 --- a/website/docs/proto/commands/plugin/add.mdx +++ b/website/docs/proto/commands/plugin/add.mdx @@ -8,8 +8,7 @@ import VersionLabel from '@site/src/components/Docs/VersionLabel'; The `proto plugin add ` command will add the provided ID and plugin locator string to -the `[plugins]` section of the local (`./.prototools`) or global (`~/.proto/.prototools`) config -file. +the `[plugins]` section of a chosen `.prototools`. ```shell $ proto plugin add node "https://github.com/moonrepo/node-plugin/releases/latest/download/node_plugin.wasm" @@ -24,4 +23,7 @@ $ proto plugin add node "https://github.com/moonrepo/node-plugin/releases/latest ### Options -- `--global` - Add to the global `~/.proto/.prototools` instead of the local `./.prototools`. +- `--global` (deprecated) - Add to the global `~/.proto/.prototools` instead of the local + `./.prototools`. +- `--to` - [Location of `.prototools`](../../config#locations) to update. + diff --git a/website/docs/proto/commands/plugin/remove.mdx b/website/docs/proto/commands/plugin/remove.mdx index a20ecf0af67..23c5c39f92b 100644 --- a/website/docs/proto/commands/plugin/remove.mdx +++ b/website/docs/proto/commands/plugin/remove.mdx @@ -8,7 +8,7 @@ import VersionLabel from '@site/src/components/Docs/VersionLabel'; The `proto plugin remove ` command will remove the provided tool ID from the `[plugins]` section -of the local (`./.prototools`) or global (`~/.proto/.prototools`) config file. +of the chosen (`.prototools`). ```shell $ proto plugin remove node @@ -22,4 +22,7 @@ $ proto plugin remove node ### Options -- `--global` - Remove from the global `~/.proto/.prototools` instead of the local `./.prototools`. +- `--from` - [Location of `.prototools`](../../config#locations) to update. + +- `--global` (deprecated) - Remove from the global `~/.proto/.prototools` instead of the local + `./.prototools`. diff --git a/website/docs/proto/commands/unalias.mdx b/website/docs/proto/commands/unalias.mdx index d1823bdf4bd..b2dc4c7f713 100644 --- a/website/docs/proto/commands/unalias.mdx +++ b/website/docs/proto/commands/unalias.mdx @@ -2,6 +2,8 @@ title: unalias --- +import VersionLabel from '@site/src/components/Docs/VersionLabel'; + The `proto unalias ` (or `proto ua`) command will remove a custom alias for the provided tool. @@ -9,12 +11,8 @@ provided tool. $ proto unalias node work ``` -By default this will update the local [`./.prototools`](../config) file. Pass `--global` to update -the global [`~/.proto/.prototools`](../config) file instead. - -```shell -$ proto unalias yarn berry --global -``` +By default this will update the local [`./.prototools`](../config) file. Pass `--from` to customize +the location. ### Arguments @@ -23,4 +21,7 @@ $ proto unalias yarn berry --global ## Options -- `--global` - Remove from the global `~/.proto/.prototools` instead of the local `./.prototools`. +- `--from` - [Location of `.prototools`](../config#locations) to update. + +- `--global` (deprecated) - Remove from the global `~/.proto/.prototools` instead of the local + `./.prototools`. diff --git a/website/docs/proto/commands/unpin.mdx b/website/docs/proto/commands/unpin.mdx index 77d9af627ca..ce9d6992ffa 100644 --- a/website/docs/proto/commands/unpin.mdx +++ b/website/docs/proto/commands/unpin.mdx @@ -6,19 +6,14 @@ import VersionLabel from '@site/src/components/Docs/VersionLabel'; -The `proto unpin ` command will unpin a version of a tool. By default it will remove from a -`./.prototools` file in the current directory. +The `proto unpin ` command will unpin a version of a tool. ```shell $ proto unpin go ``` -When the `--global` option is passed, the version will be removed globally from -`~/.proto/.prototools`. - -```shell -$ proto unpin go --global -``` +By default this will update the local [`./.prototools`](../config) file. Pass `--from` to customize +the location. ### Arguments @@ -26,4 +21,7 @@ $ proto unpin go --global ### Options -- `--global` - Unpin from the global `~/.proto/.prototools` instead of the local `./.prototools`. +- `--from` - [Location of `.prototools`](../config#locations) to update. + +- `--global` (deprecated) - Unpin from the global `~/.proto/.prototools` instead of the local + `./.prototools`. diff --git a/website/docs/proto/config.mdx b/website/docs/proto/config.mdx index 88bb8878ca5..acba18ff4cc 100644 --- a/website/docs/proto/config.mdx +++ b/website/docs/proto/config.mdx @@ -10,6 +10,30 @@ We support configuration at both the project-level and user-level using a tools, provide tool specific configuration, enable new tools via plugins, define proto settings, and more. +## Locations + +proto supports 3 locations in which a `.prototools` file can exist. These locations are used +throughout the command line and proto's own settings. + +- `local` -> `./.prototools` (current directory) +- `global` -> `~/.proto/.prototools` +- `user` -> `~/.prototools` + +> Local is a bit of a misnomer as a `.prototools` file can theoretically exist in any directory, but +> when reading/writing to a file, `local` refers to the current working directory. + +### Where to configure? + +With so many locations to store proto configuration, the question of where to store certain +configurations become blurred, especially when [resolution](#resolution-mode) comes into play. We +suggest the following locations: + +- Default/fallback [versions](#pinning-versions) of tools -> `global` +- Project specific [versions](#pinning-versions) of tools -> `local` +- Project specific [settings](#settings) -> `local` +- Shared/developer [settings](#settings) -> `user` +- Non-project related -> `user` + ## Resolution mode When a `proto` command or shim is ran, we must find and load all applicable `.prototools` files. We @@ -203,7 +227,9 @@ When defined and a tool is installed with the "latest" version, will automatical version to the configured location. Defaults to disabled or `PROTO_PIN_LATEST`. - `global` - Pins globally to `~/.proto/.prototools`. -- `local` - Pins locally to `.prototools` in current directory. +- `local` - Pins locally to `./.prototools` in current directory. +- `user` - Pins to the user's `~/.prototools` in their home directory. + ```toml title=".prototools" [settings] @@ -261,6 +287,42 @@ environment. Supports `pem` and `der` files. root-cert = "/path/to/root/cert.pem" ``` +### `[settings.offline]` + +Can be used to customize how we detect an internet connection for offline based logic. These +settings are useful if you're behind a VPN or corporate proxy. + +#### `custom-hosts` + +A list of custom hosts to ping. Will be appended to our +[default list of hosts](#override-default-hosts) and will be ran last. + +```toml title=".prototools" +[settings.offline] +custom-hosts = ["proxy.corp.domain.com:80"] +``` + +#### `override-default-hosts` + +If our default hosts are blocked or are too slow, you can disable pinging them by setting this +option to true. Our default hosts are Google DNS, Cloudflare DNS, and then Google and Mozilla hosts. + +This should be used in parallel with [`custom-hosts`](#custom-hosts). + +```toml title=".prototools" +[settings.offline] +override-default-hosts = true +``` + +#### `timeout` + +The timeout in milliseconds to wait for a ping against a host to resolve. Default timeout is 750ms. + +```toml title=".prototools" +[settings.offline] +timeout = 500 +``` + ### `[plugins]` Additional [plugins](./plugins) can be configured with the `[plugins]` section.