diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 80f9b55e18..47dfe85cd9 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -2,5 +2,4 @@ blank_issues_enabled: false contact_links: - name: Features, Bug Reports, Questions url: https://github.com/jdx/mise/discussions/new/choose - about: Our preferred starting point if you have any questions or suggestions - about configuration, features or behavior. + about: Our preferred starting point if you have any questions or suggestions about configuration, features or behavior. diff --git a/.idea/codeStyles/codeStyleConfig.xml b/.idea/codeStyles/codeStyleConfig.xml index 79ee123c2b..1a0176aca0 100644 --- a/.idea/codeStyles/codeStyleConfig.xml +++ b/.idea/codeStyles/codeStyleConfig.xml @@ -1,5 +1,5 @@ - - \ No newline at end of file + diff --git a/.prettierrc.toml b/.prettierrc.toml deleted file mode 100644 index 14e1d3a414..0000000000 --- a/.prettierrc.toml +++ /dev/null @@ -1,3 +0,0 @@ -[[overrides]] -files = "*.md" -options = { proseWrap = "always", printWidth = 120 } diff --git a/README.md b/README.md index fbfb135ad7..eb37db10a1 100644 --- a/README.md +++ b/README.md @@ -16,18 +16,15 @@ ## What is it? -- Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm) or [pyenv](https://github.com/pyenv/pyenv) - but for any language) it manages [dev tools](https://mise.jdx.dev/dev-tools/) like node, python, cmake, terraform, and - [hundreds more](https://mise.jdx.dev/registry.html). -- Like [direnv](https://github.com/direnv/direnv) it manages [environment variables](https://mise.jdx.dev/environments/) - for different project directories. -- Like [make](https://www.gnu.org/software/make/manual/make.html) it manages [tasks](https://mise.jdx.dev/tasks/) used - to build and test projects. +- Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm) or [pyenv](https://github.com/pyenv/pyenv) but for any language) it manages [dev tools](https://mise.jdx.dev/dev-tools/) like node, python, cmake, terraform, and [hundreds more](https://mise.jdx.dev/registry.html). +- Like [direnv](https://github.com/direnv/direnv) it manages [environment variables](https://mise.jdx.dev/environments/) for different project directories. +- Like [make](https://www.gnu.org/software/make/manual/make.html) it manages [tasks](https://mise.jdx.dev/tasks/) used to build and test projects. ## 30 Second Demo -The following shows using mise to install different versions of [node](https://nodejs.org). Note that calling -`which node` gives us a real path to node, not a shim. +The following shows using mise to install different versions +of [node](https://nodejs.org). +Note that calling `which node` gives us a real path to node, not a shim. [![demo](./docs/demo.gif)](./docs/demo.gif) diff --git a/SECURITY.md b/SECURITY.md index b0a024f0e1..657209aae7 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,63 +7,63 @@ Please open a ticket or send me an email if you have thoughts on how mise can be ## Core CLI Security -Development of the "core CLI" is done on jdx/mise which only a single developer (me, @jdx) has access to. Other -contributors may only submit contributions via public Pull Requests. Reducing the number of developers with access down -to 1 minimizes the chance of keys being leaked. +Development of the "core CLI" is done on jdx/mise which only a single developer (me, @jdx) has access to. +Other contributors may only submit contributions via public Pull Requests. Reducing the number +of developers with access down to 1 minimizes the chance of keys being leaked. -This does create a [bus factor](https://en.wikipedia.org/wiki/Bus_factor) problem. If I suddenly died one day or -otherwise wasn't able to continue development at all there are some successors listed in my GitHub account that can take -over my account if need be. +This does create a [bus factor](https://en.wikipedia.org/wiki/Bus_factor) problem. If I suddenly died one day +or otherwise wasn't able to continue development at all there are some successors listed in my GitHub account +that can take over my account if need be. The dependencies in the core CLI are a security vector. I've tried to be judicious about what dependencies make it into -the project. I only select dependencies with broad usage across the Rust community where possible. I'm open to PRs or -suggestions on reducing dependency count even at the cost of functionality because it will make mise more secure. +the project. I only select dependencies with broad usage across the Rust community where possible. +I'm open to PRs or suggestions on reducing dependency count even at the cost of functionality because it will make +mise more secure. ## mise.jdx.dev -mise.jdx.dev is the asset host for mise. It's used to host precompiled mise CLI binaries, and hosts a -"[VERSION](https://mise.jdx.dev/VERSION)" which mise uses to occasionally check for a new version being released. -Everything hosted there uses a single vendor to reduce surface area. +mise.jdx.dev is the asset host for mise. It's used to host precompiled mise CLI binaries, and hosts a "[VERSION](https://mise.jdx.dev/VERSION)" +which mise uses to occasionally check for a new version being released. Everything hosted there uses a single +vendor to reduce surface area. ## Cosign and slsa verification -mise will verify signatures of tools using [cosign](https://docs.sigstore.dev/) and -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier) if cosign/slsa-verifier is installed and the tool is -configured to support it. Typically, these will be tools using aqua as the backend. See the -[aqua docs](https://aquaproj.github.io/docs/reference/security/cosign-slsa) for more on how this is configured in the -[aqua registry](https://github.com/aquaproj/aqua-registry). +mise will verify signatures of tools using [cosign](https://docs.sigstore.dev/) and [slsa-verifier](https://github.com/slsa-framework/slsa-verifier) +if cosign/slsa-verifier is installed and the tool is configured to support it. Typically, these will be tools using aqua as the backend. +See the [aqua docs](https://aquaproj.github.io/docs/reference/security/cosign-slsa) for more on how this is +configured in the [aqua registry](https://github.com/aquaproj/aqua-registry). -You will see this verification happen when tools are installed, setting `--verbose` when installing tools will help make -it easier to see if verification happened. If you happen to notice a tool offers gpg/slsa/cosign/minisign/etc, see if -you can make a PR to the aqua registry for mise to pick it up. +You will see this verification happen when tools are installed, setting `--verbose` when installing tools will help +make it easier to see if verification happened. If you happen to notice a tool offers gpg/slsa/cosign/minisign/etc, see if you can +make a PR to the aqua registry for mise to pick it up. ## `mise.lock` -mise has support for [lockfiles](https://mise.jdx.dev/configuration/settings.html#lockfile) which will store/verify the -checksum of tool tarballs. Committing this into your repository is a good way to ensure that the exact same version of a -tool is installed across all developers and CI/CD systems. +mise has support for [lockfiles](https://mise.jdx.dev/configuration/settings.html#lockfile) which will +store/verify the checksum of tool tarballs. Committing this into your repository is a good way to ensure +that the exact same version of a tool is installed across all developers and CI/CD systems. Not all backends support this—notably asdf plugins do not. ## asdf plugins asdf plugins in asdf (but not with mise's default tools) are dangerous. They are typically owned by random developers -unconnected to either asdf or the tool vendor. They may get hacked or maliciously inject code into their plugin that -could trivially execute code on your machine. +unconnected to either asdf or the tool vendor. They may get hacked or maliciously inject code into +their plugin that could trivially execute code on your machine. -asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry.toml) whenever -possible. Sometimes it is not possible to use more secure backends like aqua/ubi because tools have complex install -setups or need to export env vars. As of 2025-01-08, <25% of tools use asdf plugins as the default backend. All of these -are hosted in the [mise-plugins org](https://github.com/mise-plugins) to secure the supply chain so you do not need to -rely on plugins maintained by anyone except me. +asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry.toml) whenever possible. +Sometimes it is not possible to use more secure backends like aqua/ubi because tools have complex install +setups or need to export env vars. As of 2025-01-08, <25% of tools use asdf plugins as the default backend. +All of these are hosted in the [mise-plugins org](https://github.com/mise-plugins) to secure the supply +chain so you do not need to rely on plugins maintained by anyone except me. -Of course if you _manually_ add plugins not from the mise-plugins org you will want to ensure they are coming from a -trusted source. +Of course if you _manually_ add plugins not from the mise-plugins org you will want to ensure they +are coming from a trusted source. -Please contribute to this effort to migrate away from asdf plugins by checking if a tool works in ubi or aqua and -submitting a PR to [registry.toml](https://github.com/jdx/mise/blob/main/registry.toml) to add it. If it doesn't work in -ubi or is missing from aqua, submit an issue or PR to the respective project to add it. New tools using asdf are **not** -likely to be accepted unless they cannot be supported with any other backend. +Please contribute to this effort to migrate away from asdf plugins by checking if a tool works in ubi or aqua and submitting a PR to +[registry.toml](https://github.com/jdx/mise/blob/main/registry.toml) to add it. If it doesn't work +in ubi or is missing from aqua, submit an issue or PR to the respective project to add it. New tools +using asdf are **not** likely to be accepted unless they cannot be supported with any other backend. ## Supported Versions @@ -138,7 +138,8 @@ MFPobhR7zlCShd7TdY1a41uxTGB+Wmn4DO0s/wzSgdgxIzG+TM1X47owe7l5RiI1 ## Release gpg key -This is the gpg key used to sign deb releases and the SHASUMS files contained within releases. +This is the gpg key used to sign deb releases and the SHASUMS files +contained within releases.
Release gpg key diff --git a/docs/README.md b/docs/README.md index 31e2751f8a..6af9b4bb48 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,3 @@ # mise-docs -This repository contains the documentation website for the runtime executor [mise](https://github.com/jdx/mise). The -website is powered by [VitePress](https://vitepress.dev/). +This repository contains the documentation website for the runtime executor [mise](https://github.com/jdx/mise). The website is powered by [VitePress](https://vitepress.dev/). diff --git a/docs/about.md b/docs/about.md index 1902dc53f5..b1751c4b9b 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,34 +1,42 @@ # About -`mise` (pronounced "meez") or "mise-en-place" is a development environment setup tool. The name refers to a French -culinary phrase that roughly translates to "setup" or "put in place". The idea is that before one begins cooking, they -should have all their utensils and ingredients ready to go in their place. +`mise` (pronounced "meez") or "mise-en-place" is a development environment setup tool. +The name refers to a French culinary phrase that roughly translates to "setup" or "put in place". +The idea is that before one begins cooking, they should have all their utensils and ingredients +ready to go in their place. -`mise` does the same for your projects. Using its `mise.toml` config file, you'll have a consistent way to setup and -interact with your projects no matter what language they're written in. +`mise` does the same for your projects. Using its `mise.toml` config file, +you'll have a consistent way to setup and interact with your projects no matter what +language they're written in. Its functionality is grouped into 3 categories described below. -`mise` installs and manages dev tools/runtimes like node, python, or terraform both simplifying installing these tools -and allowing you to specify which version of these tools to use in different projects. `mise` supports -[hundreds](/plugins.md) of dev tools. +`mise` installs and manages dev tools/runtimes like node, python, or terraform both +simplifying installing these tools and allowing you to specify which version of these +tools to use in different projects. `mise` supports [hundreds](/plugins.md) of dev tools. -`mise` manages environment variables letting you specify configuration like `AWS_ACCESS_KEY_ID` that may differ between -projects. It can also be used to automatically activate a [Python virtualenv](/lang/python) when entering projects too. +`mise` manages environment variables letting you specify configuration like +`AWS_ACCESS_KEY_ID` that may differ between projects. It can also be used to +automatically activate a [Python virtualenv](/lang/python) when entering projects too. -`mise` is a task runner that can be used to share common tasks within a project among developers and make things like -running tasks on file changes easy. +`mise` is a task runner that can be used to share common tasks within +a project among developers and make things like running tasks on file changes +easy. ## Contact -`mise` is mostly built and maintained by me, [Jeff Dickey](https://jdx.dev). The goal is to make local development of -software easy and consistent across languages. I have spent many years building dev tools and thinking about the -problems that `mise` addresses. - -I try to use the first-person in these docs since the reality is it's generally me writing them and I think it makes it -more interesting having a bit of my personality in the text. - -This project is simply a labor of love. I am making it because I want to make your life as a developer easier. I hope -you find it useful. Feedback is a massive driver for me. If you have anything positive or negative to say-even if it's -just to say hi-please reach out to me either on [Twitter](https://twitter.com/jdxcode), -[Mastodon](https://fosstodon.org/@jdx), [Discord](https://discord.gg/UBa7pJUN7Z), or `jdx at this domain`. +`mise` is mostly built and maintained by me, [Jeff Dickey](https://jdx.dev). The goal is +to make local development of software easy and consistent across languages. I +have spent many years building dev tools and thinking about the problems that `mise` +addresses. + +I try to use the first-person in these docs since the reality is it's generally me +writing them and I think it makes it more interesting having a bit of my personality +in the text. + +This project is simply a labor of love. I am making it because I want to make +your life as a developer easier. I hope you find it useful. Feedback is a massive +driver for me. If you have anything positive or negative to say-even if it's just +to say hi-please reach out to me either on [Twitter](https://twitter.com/jdxcode), +[Mastodon](https://fosstodon.org/@jdx), [Discord](https://discord.gg/UBa7pJUN7Z), +or `jdx at this domain`. diff --git a/docs/cache-behavior.md b/docs/cache-behavior.md index 4293ca7911..bccaa315fc 100644 --- a/docs/cache-behavior.md +++ b/docs/cache-behavior.md @@ -1,28 +1,31 @@ # Cache Behavior -mise makes use of caching in many places in order to be efficient. The details about how long to keep cache for should -eventually all be configurable. There may be gaps in the current behavior where things are hardcoded, but I'm happy to -add more settings to cover whatever config is needed. +mise makes use of caching in many places in order to be efficient. The details about how long to keep +cache for should eventually all be configurable. There may be gaps in the current behavior where +things are hardcoded, but I'm happy to add more settings to cover whatever config is needed. -Below I explain the behavior it uses around caching. If you're seeing behavior where things don't appear to be updating, -this is a good place to start. +Below I explain the behavior it uses around caching. If you're seeing behavior where things don't appear +to be updating, this is a good place to start. ## Plugin/Runtime Cache -Each plugin has a cache that's stored in `~/$MISE_CACHE_DIR/`. It stores the list of versions available for that -plugin (`mise ls-remote `), the idiomatic filenames (see below), the list of aliases, the bin directories within -each runtime installation, and the result of running `exec-env` after the runtime was installed. +Each plugin has a cache that's stored in `~/$MISE_CACHE_DIR/`. It stores +the list of versions available for that plugin (`mise ls-remote `), the idiomatic filenames (see below), +the list of aliases, the bin directories within each runtime installation, and the result of +running `exec-env` after the runtime was installed. -Remote versions are updated daily by default. The file is zlib messagepack, if you want to view it you can run the -following (requires [msgpack-cli](https://github.com/msgpack/msgpack-cli)). +Remote versions are updated daily by default. The file is zlib messagepack, if you want to view it you can +run the following (requires [msgpack-cli](https://github.com/msgpack/msgpack-cli)). ```sh cat ~/$MISE_CACHE_DIR/node/remote_versions.msgpack.z | perl -e 'use Compress::Raw::Zlib;my $d=new Compress::Raw::Zlib::Inflate();my $o;undef $/;$d->inflate(<>,$o);print $o;' | msgpack-cli decode ``` -Note that the caching of `exec-env` may be problematic if the script isn't simply exporting static values. The vast -majority of `exec-env` scripts only export static values, but if you're working with a plugin that has a dynamic -`exec-env` submit a ticket and we can try to figure out what to do. +Note that the caching of `exec-env` may be problematic if the script isn't simply exporting +static values. The vast majority of `exec-env` scripts only export static values, but if you're +working with a plugin that has a dynamic `exec-env` submit +a ticket and we can try to figure out what to do. -Caching `exec-env` massively improved the performance of mise since it requires calling bash every time mise is -initialized. Ideally, we can keep this behavior. +Caching `exec-env` massively improved the performance of mise since it requires calling bash +every time mise is initialized. Ideally, we can keep this +behavior. diff --git a/docs/configuration.md b/docs/configuration.md index 1ae948a436..6a55b3cb21 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,8 +2,7 @@ ## `mise.toml` -`mise.toml` is the config file for mise. They can be at any of the following file paths (in order of precedence, top -overrides configuration of lower paths): +`mise.toml` is the config file for mise. They can be at any of the following file paths (in order of precedence, top overrides configuration of lower paths): - `mise.local.toml` - used for local config, this should not be committed to source control - `mise.toml` @@ -12,21 +11,24 @@ overrides configuration of lower paths): - `.config/mise/config.toml` - `.config/mise/conf.d/*.toml` - all files in this directory will be loaded in alphabetical order -::: tip Run [`mise cfg`](/cli/config.html) to figure out what order mise is loading files on your particular setup. This -is often a lot easier than figuring out mise's rules. ::: +::: tip +Run [`mise cfg`](/cli/config.html) to figure out what order mise is loading files on your particular setup. This is often +a lot easier than figuring out mise's rules. +::: Notes: - Paths which start with `mise` can be dotfiles, e.g.: `mise.toml` or `.mise/config.toml`. -- This list doesn't include [Configuration Environments](/configuration/environments) which allow for - environment-specific config files like `mise.development.toml`—set with `MISE_ENV=development`. -- See [`LOCAL_CONFIG_FILENAMES` in `src/config/mod.rs`](https://github.com/jdx/mise/blob/main/src/config/mod.rs) for the - actual code for these paths and their precedence. Some legacy paths are not listed here for brevity. +- This list doesn't include [Configuration Environments](/configuration/environments) which allow for environment-specific config files like `mise.development.toml`—set with `MISE_ENV=development`. +- See [`LOCAL_CONFIG_FILENAMES` in `src/config/mod.rs`](https://github.com/jdx/mise/blob/main/src/config/mod.rs) for the actual code for these paths and their precedence. Some legacy paths are not listed here for brevity. -These files recurse upwards, so if you have a `~/src/work/myproj/mise.toml` file, what is defined there will override -anything set in `~/src/work/mise.toml` or `~/.config/mise.toml`. The config contents are merged together. +These files recurse upwards, so if you have a `~/src/work/myproj/mise.toml` file, what is defined +there will override anything set in +`~/src/work/mise.toml` or `~/.config/mise.toml`. The config contents are merged together. -:::tip Run `mise config` to see what files mise has loaded in order of precedence. ::: +:::tip +Run `mise config` to see what files mise has loaded in order of precedence. +::: Here is what a `mise.toml` looks like: @@ -59,8 +61,9 @@ run = 'echo "running build tasks"' python = 'https://github.com/asdf-community/asdf-python' ``` -`mise.toml` files are hierarchical. The configuration in a file in the current directory will override conflicting -configuration in parent directories. For example, if `~/src/myproj/mise.toml` defines the following: +`mise.toml` files are hierarchical. The configuration in a file in the current directory will +override conflicting configuration in parent directories. For example, if `~/src/myproj/mise.toml` +defines the following: ```toml [tools] @@ -76,8 +79,8 @@ node = '18' ruby = '3.1' ``` -Then when inside of `~/src/myproj/backend`, `node` will be `18`, `python` will be `3.10`, and `ruby` will be `3.1`. You -can check the active versions with `mise ls --current`. +Then when inside of `~/src/myproj/backend`, `node` will be `18`, `python` will be `3.10`, and `ruby` +will be `3.1`. You can check the active versions with `mise ls --current`. You can also have environment specific config files like `.mise.production.toml`, see [Configuration Environments](/configuration/environments) for more details. @@ -100,8 +103,8 @@ See [Settings](/configuration/settings) for the full list of settings. ### `[plugins]` - Specify Custom Plugin Repository URLs -Use `[plugins]` to add/modify plugin shortnames. Note that this will only modify _new_ plugin installations. Existing -plugins can use any URL. +Use `[plugins]` to add/modify plugin shortnames. Note that this will only modify +_new_ plugin installations. Existing plugins can use any URL. ```toml [plugins] @@ -110,16 +113,18 @@ node = "https://github.com/my-org/mise-node.git#DEADBEEF" # supports specific gi ``` If you simply want to install a plugin from a specific URL once, it's better to use -`mise plugin install plugin `. Add this section to `mise.toml` if you want to share the plugin -location/revision with other developers in your project. +`mise plugin install plugin `. Add this section to `mise.toml` if you want +to share the plugin location/revision with other developers in your project. -This is similar to [`MISE_SHORTHANDS`](https://github.com/jdx/mise#mise_shorthands_fileconfigmiseshorthandstoml) but -doesn't require a separate file. +This is similar +to [`MISE_SHORTHANDS`](https://github.com/jdx/mise#mise_shorthands_fileconfigmiseshorthandstoml) +but doesn't require a separate file. ### `[aliases]` - Tool version aliases -The following makes `mise install node@my_custom_node` install node-20.x this can also be specified in a -[plugin](/dev-tools/aliases.md). note adding an alias will also add a symlink, in this case: +The following makes `mise install node@my_custom_node` install node-20.x +this can also be specified in a [plugin](/dev-tools/aliases.md). +note adding an alias will also add a symlink, in this case: ```sh ~/.local/share/mise/installs/node/20 -> ./20.x.x @@ -131,8 +136,9 @@ my_custom_node = '20' ### Minimum mise version -Specify the minimum supported version of mise required for the configuration file. If the configuration file specifies a -version of mise that is higher than the currently installed version, mise will error out. +Specify the minimum supported version of mise required for the configuration file. +If the configuration file specifies a version of mise that is higher than +the currently installed version, mise will error out. ```toml min_version = '2024.11.1' @@ -140,20 +146,15 @@ min_version = '2024.11.1' ### `mise.toml` schema -- You can find the JSON schema for `mise.toml` [here](https://github.com/jdx/mise/blob/main/schema/mise.json) or at - . -- Some editors can load it automatically to provide autocompletion and validation for when editing a `mise.toml` file - ([VSCode](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings), - [IntelliJ](https://www.jetbrains.com/help/idea/json.html#ws_json_using_schemas), - [neovim](https://github.com/b0o/SchemaStore.nvim), etc.). It is also available in the - [JSON schema store](https://www.schemastore.org/json/). -- Note that for `included tasks` (see [task configuration](/tasks/#task-configuration), there is another schema: - ) +- You can find the JSON schema for `mise.toml` [here](https://github.com/jdx/mise/blob/main/schema/mise.json) or at . +- Some editors can load it automatically to provide autocompletion and validation for when editing a `mise.toml` file ([VSCode](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings), [IntelliJ](https://www.jetbrains.com/help/idea/json.html#ws_json_using_schemas), [neovim](https://github.com/b0o/SchemaStore.nvim), etc.). It is also available in the [JSON schema store](https://www.schemastore.org/json/). +- Note that for `included tasks` (see [task configuration](/tasks/#task-configuration), there is another schema: ) ## Global config: `~/.config/mise/config.toml` -mise can be configured in `~/.config/mise/config.toml`. It's like local `mise.toml` files except that it is used for all -directories. +mise can be configured in `~/.config/mise/config.toml`. It's like local `mise.toml` files except +that +it is used for all directories. ```toml [tools] @@ -210,14 +211,14 @@ foo = "bar" ## System config: `/etc/mise/config.toml` -Similar to `~/.config/mise/config.toml` but for all users on the system. This is useful for setting defaults for all -users. +Similar to `~/.config/mise/config.toml` but for all users on the system. This is useful for +setting defaults for all users. ## `.tool-versions` -The `.tool-versions` file is asdf's config file and it can be used in mise just like `mise.toml`. It isn't as flexible -so it's recommended to use `mise.toml` instead. It can be useful if you already have a lot of `.tool-versions` files or -work on a team that uses asdf. +The `.tool-versions` file is asdf's config file and it can be used in mise just like `mise.toml`. +It isn't as flexible so it's recommended to use `mise.toml` instead. It can be useful if you +already have a lot of `.tool-versions` files or work on a team that uses asdf. Here is an example with all the supported syntax: @@ -235,29 +236,31 @@ node sub-2:lts # install 2 versions behind the latest lts (e.g.: 18 python sub-0.1:latest # install python-3.10 if the latest is 3.11 ``` -See [the asdf docs](https://asdf-vm.com/manage/configuration.html#tool-versions) for more info on this file format. +See [the asdf docs](https://asdf-vm.com/manage/configuration.html#tool-versions) for more info on +this file format. ## Scopes Both `mise.toml` and `.tool-versions` support "scopes" which modify the behavior of the version: - `ref:` - compile from a vcs (usually git) ref -- `prefix:` - use the latest version that matches the prefix. Useful for Go since `1.20` would only match `1.20` - exactly but `prefix:1.20` will match `1.20.1` and `1.20.2` etc. -- `path:` - use a custom compiled version at the given path. One use-case is to re-use Homebrew tools (e.g.: - `path:/opt/homebrew/opt/node@20`). -- `sub-:` - subtracts PARTIAL_VERSION from ORIG_VERSION. This can be used to express - something like "2 versions behind lts" such as `sub-2:lts`. Or 1 minor version behind the latest version: - `sub-0.1:latest`. +- `prefix:` - use the latest version that matches the prefix. Useful for Go since `1.20` + would only match `1.20` exactly but `prefix:1.20` will match `1.20.1` and `1.20.2` etc. +- `path:` - use a custom compiled version at the given path. One use-case is to re-use + Homebrew tools (e.g.: `path:/opt/homebrew/opt/node@20`). +- `sub-:` - subtracts PARTIAL_VERSION from ORIG_VERSION. This can + be used to express something like "2 versions behind lts" such as `sub-2:lts`. Or 1 minor + version behind the latest version: `sub-0.1:latest`. ## Idiomatic version files -mise supports "idiomatic version files" just like asdf. They're language-specific files like `.node-version` and -`.python-version`. These are ideal for setting the runtime version of a project without forcing other developers to use -a specific tool like mise/asdf. +mise supports "idiomatic version files" just like asdf. They're language-specific files +like `.node-version` +and `.python-version`. These are ideal for setting the runtime version of a project without forcing +other developers to use a specific tool like mise/asdf. -They support aliases, which means you can have an `.nvmrc` file with `lts/hydrogen` and it will work in mise and nvm. -Here are some of the supported idiomatic version files: +They support aliases, which means you can have an `.nvmrc` file with `lts/hydrogen` and it will work +in mise and nvm. Here are some of the supported idiomatic version files: | Plugin | Idiomatic Files | | --------- | -------------------------------------------------- | @@ -271,14 +274,18 @@ Here are some of the supported idiomatic version files: | terraform | `.terraform-version`, `.packer-version`, `main.tf` | | yarn | `.yarnrc` | -In mise these are enabled by default. You can disable them with `mise settings idiomatic_version_file=false`. There is a -performance cost to having these when they're parsed as it's performed by the plugin in `bin/parse-version-file`. -However, these are [cached](/cache-behavior) so it's not a huge deal. You may not even notice. +In mise these are enabled by default. You can disable them +with `mise settings idiomatic_version_file=false`. +There is a performance cost to having these when they're parsed as it's performed by the plugin in +`bin/parse-version-file`. However, these are [cached](/cache-behavior) so it's not a huge deal. +You may not even notice. -::: info asdf called these "legacy version files". I think this was a bad name since it implies that they shouldn't be -used—which is definitely not the case IMO. I prefer the term "idiomatic" version files since they are version files not -specific to asdf/mise and can be used by other tools. (`.nvmrc` being a notable exception, which is tied to a specific -tool.) ::: +::: info +asdf called these "legacy version files". I think this was a bad name since it implies +that they shouldn't be used—which is definitely not the case IMO. I prefer the term "idiomatic" +version files since they are version files not specific to asdf/mise and can be used by other tools. +(`.nvmrc` being a notable exception, which is tied to a specific tool.) +::: ## Settings @@ -290,11 +297,13 @@ See [Tasks](/tasks/) for the full list of configuration options. ## Environment variables -::: tip Normally environment variables in mise are used to set [settings](/configuration/settings) so most environment -variables are in that doc. The following are environment variables that are not settings. +::: tip +Normally environment variables in mise are used to set [settings](/configuration/settings) so most +environment variables are in that doc. The following are environment variables that are not settings. -A setting in mise is generally something that can be configured either as an environment variable or set in a config -file. ::: +A setting in mise is generally something that can be configured either as an environment variable +or set in a config file. +::: mise can also be configured via environment variables. The following options are available: @@ -302,19 +311,22 @@ mise can also be configured via environment variables. The following options are Default: `~/.local/share/mise` or `$XDG_DATA_HOME/mise` -This is the directory where mise stores plugins and tool installs. These are not supposed to be shared across machines. +This is the directory where mise stores plugins and tool installs. These are not supposed to be +shared +across machines. ### `MISE_CACHE_DIR` -Default (Linux): `~/.cache/mise` or `$XDG_CACHE_HOME/mise` Default (macOS): `~/Library/Caches/mise` or -`$XDG_CACHE_HOME/mise` +Default (Linux): `~/.cache/mise` or `$XDG_CACHE_HOME/mise` +Default (macOS): `~/Library/Caches/mise` or `$XDG_CACHE_HOME/mise` -This is the directory where mise stores internal cache. This is not supposed to be shared across machines. It may be -deleted at any time mise is not running. +This is the directory where mise stores internal cache. This is not supposed to be shared +across machines. It may be deleted at any time mise is not running. ### `MISE_TMP_DIR` -Default: [`std::env::temp_dir()`](https://doc.rust-lang.org/std/env/fn.temp_dir.html) implementation in rust +Default: [`std::env::temp_dir()`](https://doc.rust-lang.org/std/env/fn.temp_dir.html) implementation +in rust This is used for temporary storage such as when installing tools. @@ -338,17 +350,18 @@ This is the path which is used as `{{config_root}}` for the global config file. ### `MISE_ENV_FILE` -Set to a filename to read from env from a dotenv file. e.g.: `MISE_ENV_FILE=.env`. Uses -[dotenvy](https://crates.io/crates/dotenvy) under the hood. +Set to a filename to read from env from a dotenv file. e.g.: `MISE_ENV_FILE=.env`. +Uses [dotenvy](https://crates.io/crates/dotenvy) under the hood. ### `MISE_${PLUGIN}_VERSION` -Set the version for a runtime. For example, `MISE_NODE_VERSION=20` will use regardless of what is set in -`mise.toml`/`.tool-versions`. +Set the version for a runtime. For example, `MISE_NODE_VERSION=20` will use regardless +of what is set in `mise.toml`/`.tool-versions`. ### `MISE_TRUSTED_CONFIG_PATHS` -This is a list of paths that mise will automatically mark as trusted. They can be separated with `:`. +This is a list of paths that mise will automatically mark as +trusted. They can be separated with `:`. ### `MISE_LOG_LEVEL=trace|debug|info|warn|error` @@ -363,8 +376,8 @@ Output logs to a file. ### `MISE_LOG_FILE_LEVEL=trace|debug|info|warn|error` -Same as `MISE_LOG_LEVEL` but for the log _file_ output level. This is useful if you want to store the logs but not have -them litter your display. +Same as `MISE_LOG_LEVEL` but for the log _file_ output level. This is useful if you want +to store the logs but not have them litter your display. ### `MISE_QUIET=1` @@ -376,15 +389,16 @@ Set the timeout for http requests in seconds. The default is `30`. ### `MISE_RAW=1` -Set to "1" to directly pipe plugin scripts to stdin/stdout/stderr. By default stdin is disabled because when installing -a bunch of plugins in parallel you won't see the prompt. Use this if a plugin accepts input or otherwise does not seem -to be installing correctly. +Set to "1" to directly pipe plugin scripts to stdin/stdout/stderr. By default stdin is disabled +because when installing a bunch of plugins in parallel you won't see the prompt. Use this if a +plugin accepts input or otherwise does not seem to be installing correctly. Sets `MISE_JOBS=1` because only 1 plugin script can be executed at a time. ### `MISE_FISH_AUTO_ACTIVATE=1` -Configures the vendor_conf.d script for fish shell to automatically activate. This file is automatically used in -homebrew and potentially other installs to automatically activate mise without configuring. +Configures the vendor_conf.d script for fish shell to automatically activate. +This file is automatically used in homebrew and potentially other installs to +automatically activate mise without configuring. Defaults to enabled, set to "0" to disable. diff --git a/docs/configuration/environments.md b/docs/configuration/environments.md index 787747cc1b..039b8e9834 100644 --- a/docs/configuration/environments.md +++ b/docs/configuration/environments.md @@ -1,13 +1,14 @@ # Config Environments -It's possible to have separate `mise.toml` files in the same directory for different environments like `development` and -`production`. To enable, either set the `-E,--env` option or `MISE_ENV` environment variable to an environment like -`development` or `production`. mise will then look for a `mise.{MISE_ENV}.toml` file in the current directory, parent -directories and the `MISE_CONFIG_DIR` directory. +It's possible to have separate `mise.toml` files in the same directory for different +environments like `development` and `production`. To enable, either set the `-E,--env` option or `MISE_ENV` environment +variable to an environment like `development` or `production`. mise will then look for a `mise.{MISE_ENV}.toml` file +in the current directory, parent directories and the `MISE_CONFIG_DIR` directory. -mise will also look for "local" files like `mise.local.toml` and `mise.{MISE_ENV}.local.toml` in the current directory -and parent directories. These are intended to not be committed to version control. (Add `mise.local.toml` and -`mise.*.local.toml` to your `.gitignore` file.) +mise will also look for "local" files like `mise.local.toml` and `mise.{MISE_ENV}.local.toml` +in the current directory and parent directories. +These are intended to not be committed to version control. +(Add `mise.local.toml` and `mise.*.local.toml` to your `.gitignore` file.) The priority of these files goes in this order (top overrides bottom): @@ -18,12 +19,12 @@ The priority of these files goes in this order (top overrides bottom): If `MISE_OVERRIDE_CONFIG_FILENAMES` is set, that will be used instead of all of this. -You can also use paths like `mise/config.{MISE_ENV}.toml` or `.config/mise.{MISE_ENV}.toml` Those rules follow the order -in [Configuration](/configuration). +You can also use paths like `mise/config.{MISE_ENV}.toml` or `.config/mise.{MISE_ENV}.toml` Those rules +follow the order in [Configuration](/configuration). Use `mise config` to see which files are being used. -The rules around which file is written are different because we ultimately need to choose one. See the docs for -[`mise use`](/cli/use.html) for more information. +The rules around which file is written are different because we ultimately need to choose one. See +the docs for [`mise use`](/cli/use.html) for more information. Multiple environments can be specified, e.g. `MISE_ENV=ci,test` with the last one taking precedence. diff --git a/docs/configuration/settings.md b/docs/configuration/settings.md index f51bbd5021..b6a492c404 100644 --- a/docs/configuration/settings.md +++ b/docs/configuration/settings.md @@ -4,8 +4,8 @@ import Settings from '/components/settings.vue'; -The following is a list of all of mise's settings. These can be set via `mise settings key=value`, by directly modifying -`~/.config/mise/config.toml` or local config, or via environment variables. +The following is a list of all of mise's settings. These can be set via `mise settings key=value`, +by directly modifying `~/.config/mise/config.toml` or local config, or via environment variables. Some of them also can be set via global CLI flags. diff --git a/docs/contact.md b/docs/contact.md index aedef53072..e7b1815e7e 100644 --- a/docs/contact.md +++ b/docs/contact.md @@ -1,13 +1,17 @@ # Contact -`mise` is mostly built and maintained by me, [Jeff Dickey](https://jdx.dev). The goal is to make local development of -software easy and consistent across languages. I have spent many years building dev tools and thinking about the -problems that `mise` addresses. +`mise` is mostly built and maintained by me, [Jeff Dickey](https://jdx.dev). The goal is +to make local development of software easy and consistent across languages. I +have spent many years building dev tools and thinking about the problems that `mise` +addresses. -I try to use the first-person in these docs since the reality is it's generally me writing them and I think it makes it -more interesting having a bit of my personality in the text. +I try to use the first-person in these docs since the reality is it's generally me +writing them and I think it makes it more interesting having a bit of my personality +in the text. -This project is simply a labor of love. I am making it because I want to make your life as a developer easier. I hope -you find it useful. Feedback is a massive driver for me. If you have anything positive or negative to say-even if it's -just to say hi-please reach out to me either on [Twitter](https://twitter.com/jdxcode), -[Mastodon](https://fosstodon.org/@jdx), [Discord](https://discord.gg/UBa7pJUN7Z), or `jdx at this domain`. +This project is simply a labor of love. I am making it because I want to make +your life as a developer easier. I hope you find it useful. Feedback is a massive +driver for me. If you have anything positive or negative to say-even if it's just +to say hi-please reach out to me either on [Twitter](https://twitter.com/jdxcode), +[Mastodon](https://fosstodon.org/@jdx), [Discord](https://discord.gg/UBa7pJUN7Z), +or `jdx at this domain`. diff --git a/docs/continuous-integration.md b/docs/continuous-integration.md index 92dadbac5d..5e0ff57723 100644 --- a/docs/continuous-integration.md +++ b/docs/continuous-integration.md @@ -5,8 +5,7 @@ We recommend that your project pins the tools to a specific version to ensure th ## Any CI provider -Continuous integration pipelines allow running arbitrary commands. You can use this to install Mise and run -`mise install` to install the tools: +Continuous integration pipelines allow running arbitrary commands. You can use this to install Mise and run `mise install` to install the tools: ```yaml script: | @@ -25,8 +24,7 @@ Alternatively, you can add the [shims](/dev-tools/shims.md) directory to your `P ## GitHub Actions -If you use GitHub Actions, we provide a [mise-action](https://github.com/jdx/mise-action) that wraps the installation of -Mise and the tools. All you need to do is to add the action to your workflow: +If you use GitHub Actions, we provide a [mise-action](https://github.com/jdx/mise-action) that wraps the installation of Mise and the tools. All you need to do is to add the action to your workflow: ```yaml name: test @@ -60,8 +58,9 @@ jobs: ## GitLab CI -You can use any docker image with `mise` installed to run your CI jobs. Here's an example using `debian-slim` as base -image: ::: details +You can use any docker image with `mise` installed to run your CI jobs. +Here's an example using `debian-slim` as base image: +::: details ```dockerfile FROM debian:12-slim @@ -100,9 +99,7 @@ build-job: ## Xcode Cloud -If you are using Xcode Cloud, you can use custom `ci_post_clone.sh` -[build script](https://developer.apple.com/documentation/xcode/writing-custom-build-scripts) to install Mise. Here's an -example: +If you are using Xcode Cloud, you can use custom `ci_post_clone.sh` [build script](https://developer.apple.com/documentation/xcode/writing-custom-build-scripts) to install Mise. Here's an example: ```bash #!/bin/sh diff --git a/docs/contributing.md b/docs/contributing.md index 59e48a0b88..83b27aeb4b 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,21 +1,16 @@ # Contributing -Before submitting a PR, unless it's something obvious, consider filing an issue or simply mention what you plan to do in -the [Discord](https://discord.gg/UBa7pJUN7Z). PRs are often either rejected or need to change significantly after -submission so make sure before you start working on something it won't be a wasted effort. +Before submitting a PR, unless it's something obvious, consider filing an issue or simply mention what you plan to do in the [Discord](https://discord.gg/UBa7pJUN7Z). +PRs are often either rejected or need to change significantly after submission so make sure before you start working on something it won't be a wasted effort. -Issues ideal for contributors can be found with the -["help wanted"](https://github.com/jdx/mise/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and -["good first issue"](https://github.com/jdx/mise/labels/good%20first%20issue) labels. These are isssues that I feel are -self-contained therefore don't require super in-depth understanding of the codebase or that require knowledge about -something I don't understand very well myself. +Issues ideal for contributors can be found with the ["help wanted"](https://github.com/jdx/mise/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and ["good first issue"](https://github.com/jdx/mise/labels/good%20first%20issue) labels. These are isssues that I feel are self-contained therefore don't require super in-depth understanding of the codebase or that require knowledge about something I don't understand very well myself. ## Testing ### Unit Tests -Unit tests are used for fast, relatively simple logic. They can be run with `cargo test`. The dev container is -recommended for executing since it does not require having a proper local setup. +Unit tests are used for fast, relatively simple logic. They can be run with `cargo test`. The dev container is recommended +for executing since it does not require having a proper local setup. To run locally you will need to first disable mise if you are using it. @@ -58,10 +53,8 @@ pwsh e2e-win\run.ps1 task # run tests matching `*task*` ## Dependencies -- [rust](https://www.rust-lang.org/) stable 1.70.0+ (I test with the beta channel locally, but CI uses stable, you can - use whatever) -- [just](https://github.com/casey/just) this should be removed in favor of mise tasks but it's still used for some - things. +- [rust](https://www.rust-lang.org/) stable 1.70.0+ (I test with the beta channel locally, but CI uses stable, you can use whatever) +- [just](https://github.com/casey/just) this should be removed in favor of mise tasks but it's still used for some things. ## Tasks @@ -91,13 +84,14 @@ test:e2e ~/src/mise/.mise.to ## Setup -Shouldn't require anything special I'm aware of, but `mise run build` is a good sanity check to run and make sure it's -all working. +Shouldn't require anything special I'm aware of, but `mise run build` is a good sanity check to run and make sure it's all working. ## Dev Container -::: danger The docker setup quit working and since I don't use it I haven't bothered to fix it. For now you'll need to -run outside of docker or you can try to fix the docker setup. ::: +::: danger +The docker setup quit working and since I don't use it I haven't bothered to fix it. For now you'll need to run outside of +docker or you can try to fix the docker setup. +::: There is a docker setup that makes development with mise easier. It is especially helpful for running the E2E tests. Here's some example ways to use it: @@ -112,20 +106,22 @@ mise run docker:e2e # shortcut for `mise run docker:mise run test:e2e` ## Pre-commit hook -You can optionally run a pre-commit hook which lints the codebase and updates generated code. To do this, install -[lefthook](https://github.com/evilmartians/lefthook) and run `lefthook install`. +You can optionally run a pre-commit hook which lints the codebase and updates generated code. +To do this, install [lefthook](https://github.com/evilmartians/lefthook) and run `lefthook install`. ## Running the CLI -Even if using the devcontainer, it's a good idea to create a shim to make it easy to launch mise. I use the following -shim in `~/.local/bin/@mise`: +Even if using the devcontainer, it's a good idea to create a shim to make it easy to launch mise. I use the following shim +in `~/.local/bin/@mise`: ```sh #!/bin/sh exec cargo run -q --all-features --manifest-path ~/src/mise/Cargo.toml -- "$@" ``` -::: info Don't forget to change the manifest path to the correct path for your setup. ::: +::: info +Don't forget to change the manifest path to the correct path for your setup. +::: Then if that is in PATH just use `@mise` to run mise by compiling it on the fly. @@ -153,8 +149,7 @@ mise run render ## Adding a new setting -To add a new setting, add it to [`settings.toml`](https://github.com/jdx/mise/blob/main/settings.toml) in the root of -the project and run `mise run render` to update the codebase. +To add a new setting, add it to [`settings.toml`](https://github.com/jdx/mise/blob/main/settings.toml) in the root of the project and run `mise run render` to update the codebase. ## Testing packaging diff --git a/docs/core-tools.md b/docs/core-tools.md index a8101d189a..337513ecda 100644 --- a/docs/core-tools.md +++ b/docs/core-tools.md @@ -1,9 +1,9 @@ # Core Tools -`mise` comes with some plugins built into the CLI written in Rust. These are new and will improve over time. +`mise` comes with some plugins built into the CLI written in Rust. These are new and will improve over +time. -They can be easily overridden by installing an asdf/vfox plugin with the same name, e.g.: -`mise plugin install python https://github.com/asdf-community/asdf-python`. +They can be easily overridden by installing an asdf/vfox plugin with the same name, e.g.: `mise plugin install python https://github.com/asdf-community/asdf-python`. You can see the core plugins with `mise registry -b core`. diff --git a/docs/demo.md b/docs/demo.md index f7dde15927..e1b1ba4d5b 100644 --- a/docs/demo.md +++ b/docs/demo.md @@ -1,6 +1,7 @@ # 30 Second Demo -The following shows using mise to install different versions of [node](https://nodejs.org). Note that calling -`which node` gives us a real path to node, not a shim. +The following shows using mise to install different versions +of [node](https://nodejs.org). +Note that calling `which node` gives us a real path to node, not a shim. [![demo](https://github.com/jdx/mise/blob/main/docs/demo.gif?raw=true)](https://github.com/jdx/mise/blob/main/docs/demo.gif) diff --git a/docs/dev-tools/aliases.md b/docs/dev-tools/aliases.md index fbad5f277f..f5a99b3de4 100644 --- a/docs/dev-tools/aliases.md +++ b/docs/dev-tools/aliases.md @@ -2,8 +2,8 @@ ## Aliased Backends -Tools can be aliased so that something like `node` which normally maps to `core:node` can be changed to something like -`asdf:company/our-custom-node` instead. +Tools can be aliased so that something like `node` which normally maps to `core:node` can be changed +to something like `asdf:company/our-custom-node` instead. ```toml [alias] @@ -13,9 +13,9 @@ erlang = 'asdf:https://github.com/company/our-custom-erlang' ## Aliased Versions -mise supports aliasing the versions of runtimes. One use-case for this is to define aliases for LTS versions of -runtimes. For example, you may want to specify `lts-hydrogen` as the version for so you can use set it with -`node lts-hydrogen` in `mise.toml`/`.tool-versions`. +mise supports aliasing the versions of runtimes. One use-case for this is to define aliases for LTS +versions of runtimes. For example, you may want to specify `lts-hydrogen` as the version for +so you can use set it with `node lts-hydrogen` in `mise.toml`/`.tool-versions`. User aliases can be created by adding an `alias.` section to `~/.config/mise/config.toml`: @@ -24,7 +24,8 @@ User aliases can be created by adding an `alias.` section to `~/.config/ my_custom_20 = '20' ``` -Plugins can also provide aliases via a `bin/list-aliases` script. Here is an example showing node.js versions: +Plugins can also provide aliases via a `bin/list-aliases` script. Here is an example showing node.js +versions: ```bash #!/usr/bin/env bash @@ -34,8 +35,10 @@ echo "lts-gallium 16" echo "lts-fermium 14" ``` -::: info Because this is mise-specific functionality not currently used by asdf it isn't likely to be in any plugin -currently, but plugin authors can add this script without impacting asdf users. ::: +::: info +Because this is mise-specific functionality not currently used by asdf it isn't likely to be in any +plugin currently, but plugin authors can add this script without impacting asdf users. +::: ## Templates diff --git a/docs/dev-tools/backends/aqua.md b/docs/dev-tools/backends/aqua.md index b41b31def2..b822bd3873 100644 --- a/docs/dev-tools/backends/aqua.md +++ b/docs/dev-tools/backends/aqua.md @@ -1,29 +1,27 @@ # Aqua Backend -[Aqua](https://aquaproj.github.io/) tools may be used natively in mise. aqua is the ideal backend to use for new tools -since they don't require plugins, they work on windows, they offer security features like cosign/slsa verification in -addition to checksums. aqua installs also show more progress bars, which is nice. - -You do not need to separately install aqua. The aqua CLI is not used in mise at all. What is used is the -[aqua registry](https://github.com/aquaproj/aqua-registry) which is a bunch of yaml files that get compiled into the -mise binary on release. Here's an example of one of these files: -[`aqua:hashicorp/terraform`](https://github.com/aquaproj/aqua-registry/blob/main/pkgs/hashicorp/terraform/registry.yaml). +[Aqua](https://aquaproj.github.io/) tools may be used natively in mise. aqua is the ideal backend +to use for new tools since they don't require plugins, they work on windows, they offer security +features like cosign/slsa verification in addition to checksums. aqua installs also show more progress +bars, which is nice. + +You do not need to separately install aqua. The aqua CLI is not used in mise at all. What is used is +the [aqua registry](https://github.com/aquaproj/aqua-registry) which is a bunch of yaml files that get compiled into the mise binary on release. +Here's an example of one of these files: [`aqua:hashicorp/terraform`](https://github.com/aquaproj/aqua-registry/blob/main/pkgs/hashicorp/terraform/registry.yaml). mise has a reimplementation of aqua that knows how to work with these files to install tools. -As of this writing, aqua is relatively new to mise and because a lot of tools are being converted from asdf to aqua, -there may be some configuration in aqua tools that need to be tightened up. I put some common issues below and would -strongly recommend contributing changes back to the aqua registry if you notice problems. The maintainer is super -responsive and great to work with. +As of this writing, aqua is relatively new to mise and because a lot of tools are being converted from +asdf to aqua, there may be some configuration in aqua tools that need to be tightened up. I put some +common issues below and would strongly recommend contributing changes back to the aqua registry if you +notice problems. The maintainer is super responsive and great to work with. -If all else fails, you can disable aqua entirely with -[`MISE_DISABLE_BACKENDS=aqua`](/configuration/settings.html#disable_backends). +If all else fails, you can disable aqua entirely with [`MISE_DISABLE_BACKENDS=aqua`](/configuration/settings.html#disable_backends). -Currently aqua tools don't support setting environment variables or doing more than simply downloading binaries though -(and I'm not sure this functionality would ever get added), so some tools will likely always require plugins like -asdf/vfox. +Currently aqua tools don't support setting environment variables or doing more than simply downloading +binaries though (and I'm not sure this functionality would ever get added), so some tools will likely +always require plugins like asdf/vfox. -The code for this is inside the mise repository at -[`./src/backend/aqua.rs`](https://github.com/jdx/mise/blob/main/src/backend/aqua.rs). +The code for this is inside the mise repository at [`./src/backend/aqua.rs`](https://github.com/jdx/mise/blob/main/src/backend/aqua.rs). ## Usage @@ -42,9 +40,8 @@ The version will be set in `~/.config/mise/config.toml` with the following forma "aqua:BurntSushi/ripgrep" = "latest" ``` -Some tools will default to use aqua if they're specified in -[registry.toml](https://github.com/jdx/mise/blob/main/registry.toml) to use the aqua backend. To see these tools, run -`mise registry | grep aqua:`. +Some tools will default to use aqua if they're specified in [registry.toml](https://github.com/jdx/mise/blob/main/registry.toml) +to use the aqua backend. To see these tools, run `mise registry | grep aqua:`. ## Settings @@ -59,22 +56,24 @@ Here's some common issues I've seen when working with aqua tools. ### Supported env missing -The aqua registry defines supported envs for each tool of the os/arch. I've noticed some of these are simply missing -os/arch combos that are in fact supported—possibly because it was added after the registry was created for that tool. +The aqua registry defines supported envs for each tool of the os/arch. I've noticed some of these +are simply missing os/arch combos that are in fact supported—possibly because it was added after +the registry was created for that tool. The fix is simple, just edit the `supported_envs` section of `registry.yaml` for the tool in question. ### Using `version_filter` instead of `version_prefix` -This is a weird one that causes weird issues in mise. In general in mise we like versions like `1.2.3` with no -decoration like `v1.2.3` or `cli-v1.2.3`. This consistency not only makes `mise.toml` cleaner but, it also helps make -things like `mise up` function right because it's able to parse it as semver without dealing with a bunch of edge-cases. +This is a weird one that causes weird issues in mise. In general in mise we like versions like +`1.2.3` with no decoration like `v1.2.3` or `cli-v1.2.3`. This consistency not only makes `mise.toml` +cleaner but, it also helps make things like `mise up` function right because it's able to parse it as +semver without dealing with a bunch of edge-cases. Really if you notice aqua tools are giving you versions that aren't simple triplets, it's worth fixing. -One common thing I've seen is registries using a `version_filter` expression like -`Version startsWith "Version startsWith "atlascli/""`. +One common thing I've seen is registries using a `version_filter` expression like `Version startsWith "Version startsWith "atlascli/""`. -This ultimately causes the version to be `atlascli/1.2.3` which is not what we want. The fix is to use `version_prefix` -instead of `version_filter` and just put the prefix in the `version_prefix` field. In this example, it would be -`atlascli/`. mise will automatically strip this out and add it back in, which it can't do with `version_filter`. +This ultimately causes the version to be `atlascli/1.2.3` which is not what we want. The fix is to use +`version_prefix` instead of `version_filter` and just put the prefix in the `version_prefix` field. +In this example, it would be `atlascli/`. mise will automatically strip this out and add it back in, +which it can't do with `version_filter`. diff --git a/docs/dev-tools/backends/asdf.md b/docs/dev-tools/backends/asdf.md index 979dbba919..731aac0438 100644 --- a/docs/dev-tools/backends/asdf.md +++ b/docs/dev-tools/backends/asdf.md @@ -1,10 +1,12 @@ # asdf Backend -asdf is the original backend for mise. It relies on asdf plugins for each tool. asdf plugins are more risky to use -because they're typically written by a single developer unrelated to the tool vendor they also do not function on -Windows. Because of the extra complexity of asdf tools and security concerns we are actively moving tools in the -registry away from asdf where possible to backends like aqua and ubi which don't require plugins. That said, not all -tools can function with ubi/aqua if they have a unique installation process or need to set env vars other than PATH. +asdf is the original backend for mise. It relies on asdf plugins for each tool. asdf plugins are +more risky to use because they're typically written by a single developer unrelated to the tool vendor +they also do not function on Windows. +Because of the extra complexity of asdf tools and security concerns we are actively moving tools in +the registry away from asdf where possible to backends like aqua and ubi which don't require plugins. +That said, not all tools can function with ubi/aqua if they have a unique installation process or +need to set env vars other than PATH. ## Writing asdf plugins for mise diff --git a/docs/dev-tools/backends/cargo.md b/docs/dev-tools/backends/cargo.md index 4a24725f5a..d9ce5c98d1 100644 --- a/docs/dev-tools/backends/cargo.md +++ b/docs/dev-tools/backends/cargo.md @@ -1,13 +1,14 @@ # Cargo Backend -You may install packages directly from [Cargo Crates](https://crates.io/) even if there isn't an asdf plugin for it. +You may install packages directly from [Cargo Crates](https://crates.io/) even if there +isn't an asdf plugin for it. -The code for this is inside the mise repository at -[`./src/backend/cargo.rs`](https://github.com/jdx/mise/blob/main/src/backend/cargo.rs). +The code for this is inside the mise repository at [`./src/backend/cargo.rs`](https://github.com/jdx/mise/blob/main/src/backend/cargo.rs). ## Dependencies -This relies on having `cargo` installed. You can either install it on your system via [rustup](https://rustup.rs/): +This relies on having `cargo` installed. You can either install it on your +system via [rustup](https://rustup.rs/): ```sh curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh @@ -21,8 +22,8 @@ mise use -g rust ## Usage -The following installs the latest version of [eza](https://crates.io/crates/eza) and sets it as the active version on -PATH: +The following installs the latest version of [eza](https://crates.io/crates/eza) and +sets it as the active version on PATH: ```sh $ mise use -g cargo:eza @@ -41,8 +42,8 @@ The version will be set in `~/.config/mise/config.toml` with the following forma ### Using Git -You can install any package from a Git repository using the `mise` command. This allows you to install a particular tag, -branch, or commit revision: +You can install any package from a Git repository using the `mise` command. This allows you to +install a particular tag, branch, or commit revision: ```sh # Install a specific tag @@ -68,8 +69,8 @@ import Settings from '/components/settings.vue'; ## Tool Options -The following [tool-options](/dev-tools/#tool-options) are available for the `cargo` backend—these go in `[tools]` in -`mise.toml`. +The following [tool-options](/dev-tools/#tool-options) are available for the `cargo` backend—these +go in `[tools]` in `mise.toml`. ### `features` @@ -100,7 +101,8 @@ Select the CLI bin name to install when multiple are available (passed as `cargo ### `crate` -Select the crate name to install when multiple are available (passed as `cargo install --git= `): +Select the crate name to install when multiple are available (passed as +`cargo install --git= `): ```toml [tools] @@ -109,8 +111,8 @@ Select the crate name to install when multiple are available (passed as `cargo i ### `locked` -Use Cargo.lock (passes `cargo install --locked`) when building CLI. This is the default behavior, pass `false` to -disable: +Use Cargo.lock (passes `cargo install --locked`) when building CLI. This is the default behavior, +pass `false` to disable: ```toml [tools] diff --git a/docs/dev-tools/backends/dotnet.md b/docs/dev-tools/backends/dotnet.md index d695727c38..d269825a6f 100644 --- a/docs/dev-tools/backends/dotnet.md +++ b/docs/dev-tools/backends/dotnet.md @@ -1,12 +1,11 @@ # Dotnet backend -The code for this is inside the mise repository at -[`./src/backend/dotnet.rs`](https://github.com/jdx/mise/blob/main/src/backend/dotnet.rs). +The code for this is inside the mise repository at [`./src/backend/dotnet.rs`](https://github.com/jdx/mise/blob/main/src/backend/dotnet.rs). ## Usage -The following installs the latest version of [GitVersion.Tool](https://gitversion.net/) and sets it as the active -version on PATH: +The following installs the latest version of [GitVersion.Tool](https://gitversion.net/) and +sets it as the active version on PATH: ```sh $ mise use -g dotnet:GitVersion.Tool@5.12.0 @@ -52,5 +51,5 @@ import Settings from '/components/settings.vue'; ## Tool Options -The following [tool-options](/dev-tools/#tool-options) are available for the `dotnet` backend—these go in `[tools]` in -`mise.toml`. +The following [tool-options](/dev-tools/#tool-options) are available for the `dotnet` backend—these +go in `[tools]` in `mise.toml`. diff --git a/docs/dev-tools/backends/gem.md b/docs/dev-tools/backends/gem.md index 22331c5884..9b586f9a26 100644 --- a/docs/dev-tools/backends/gem.md +++ b/docs/dev-tools/backends/gem.md @@ -1,12 +1,11 @@ # gem Backend -mise can be used to install CLIs from RubyGems. The code for this is inside of the mise repository at -[`./src/backend/gem.rs`](https://github.com/jdx/mise/blob/main/src/backend/pipx.rs). +mise can be used to install CLIs from RubyGems. The code for this is inside of the mise repository at [`./src/backend/gem.rs`](https://github.com/jdx/mise/blob/main/src/backend/pipx.rs). ## Dependencies -This relies on having `gem` (provided with ruby) installed. You can install it with or without mise. Here is how to -install `ruby` with mise: +This relies on having `gem` (provided with ruby) installed. You can install it with or without mise. +Here is how to install `ruby` with mise: ```sh mise use -g ruby @@ -14,8 +13,7 @@ mise use -g ruby ## Usage -The following installs the latest version of [rubocop](https://rubygems.org/gems/rubocop) and sets it as the active -version on PATH: +The following installs the latest version of [rubocop](https://rubygems.org/gems/rubocop) and sets it as the active version on PATH: ```sh mise use -g gem:rubocop @@ -31,8 +29,8 @@ The version will be set in `~/.config/mise/config.toml` with the following forma ## Ruby upgrades -If the ruby version used by a gem package changes, (by mise or system ruby), you may need to reinstall the gem. This can -be done with: +If the ruby version used by a gem package changes, (by mise or system ruby), you may need to +reinstall the gem. This can be done with: ```sh mise install -f gem:rubocop diff --git a/docs/dev-tools/backends/go.md b/docs/dev-tools/backends/go.md index dc9e5fa2d7..b6c52b4bb5 100644 --- a/docs/dev-tools/backends/go.md +++ b/docs/dev-tools/backends/go.md @@ -1,10 +1,9 @@ # Go Backend -You may install packages directly via [go install](https://go.dev/doc/install) even if there isn't an asdf plugin for -it. +You may install packages directly via [go install](https://go.dev/doc/install) even if there +isn't an asdf plugin for it. -The code for this is inside of the mise repository at -[`./src/backend/go.rs`](https://github.com/jdx/mise/blob/main/src/backend/go.rs). +The code for this is inside of the mise repository at [`./src/backend/go.rs`](https://github.com/jdx/mise/blob/main/src/backend/go.rs). ## Dependencies @@ -14,13 +13,15 @@ This relies on having `go` installed. Which you can install via mise: mise use -g go ``` -::: tip Any method of installing `go` is fine if you want to install go some other way. mise will use whatever `go` is -on PATH. ::: +::: tip +Any method of installing `go` is fine if you want to install go some other way. +mise will use whatever `go` is on PATH. +::: ## Usage -The following installs the latest version of [hivemind](https://github.com/DarthSim/hivemind) and sets it as the active -version on PATH: +The following installs the latest version of [hivemind](https://github.com/DarthSim/hivemind) and +sets it as the active version on PATH: ```sh $ mise use -g go:github.com/DarthSim/hivemind diff --git a/docs/dev-tools/backends/index.md b/docs/dev-tools/backends/index.md index 800da8bce2..440a77e773 100644 --- a/docs/dev-tools/backends/index.md +++ b/docs/dev-tools/backends/index.md @@ -14,5 +14,7 @@ In addition to asdf plugins, you can also directly install CLIs with some packag - [ubi](/dev-tools/backends/ubi) - [vfox](/dev-tools/backends/vfox) -::: tip If you'd like to contribute a new backend to mise, they're not difficult to write. See -[`./src/backend/`](https://github.com/jdx/mise/tree/main/src/backend) for examples. ::: +::: tip +If you'd like to contribute a new backend to mise, they're not difficult to write. +See [`./src/backend/`](https://github.com/jdx/mise/tree/main/src/backend) for examples. +::: diff --git a/docs/dev-tools/backends/npm.md b/docs/dev-tools/backends/npm.md index 2170e20b0b..575010eaf4 100644 --- a/docs/dev-tools/backends/npm.md +++ b/docs/dev-tools/backends/npm.md @@ -1,13 +1,14 @@ # npm Backend -You may install packages directly from [npmjs.org](https://npmjs.org/) even if there isn't an asdf plugin for it. +You may install packages directly from [npmjs.org](https://npmjs.org/) even if there +isn't an asdf plugin for it. -The code for this is inside of the mise repository at -[`./src/backend/npm.rs`](https://github.com/jdx/mise/blob/main/src/backend/npm.rs). +The code for this is inside of the mise repository at [`./src/backend/npm.rs`](https://github.com/jdx/mise/blob/main/src/backend/npm.rs). ## Dependencies -This relies on having `npm` installed. You can install it with or without mise. Here is how to install `npm` with mise: +This relies on having `npm` installed. You can install it with or without mise. +Here is how to install `npm` with mise: ```sh mise use -g node @@ -15,8 +16,8 @@ mise use -g node ## Usage -The following installs the latest version of [prettier](https://www.npmjs.com/package/prettier) and sets it as the -active version on PATH: +The following installs the latest version of [prettier](https://www.npmjs.com/package/prettier) +and sets it as the active version on PATH: ```sh $ mise use -g npm:prettier diff --git a/docs/dev-tools/backends/pipx.md b/docs/dev-tools/backends/pipx.md index d6a6acbdad..ad047e2e53 100644 --- a/docs/dev-tools/backends/pipx.md +++ b/docs/dev-tools/backends/pipx.md @@ -7,13 +7,12 @@ You may install python packages directly from: - GitHub - Http -The code for this is inside of the mise repository at -[`./src/backend/pipx.rs`](https://github.com/jdx/mise/blob/main/src/backend/pipx.rs). +The code for this is inside of the mise repository at [`./src/backend/pipx.rs`](https://github.com/jdx/mise/blob/main/src/backend/pipx.rs). ## Dependencies -This relies on having `pipx` installed. You can install it with or without mise. Here is how to install `pipx` with -mise: +This relies on having `pipx` installed. You can install it with or without mise. +Here is how to install `pipx` with mise: ```sh mise use -g python @@ -24,8 +23,8 @@ Other installation instructions can be found [here](https://pipx.pypa.io/latest/ ## Usage -The following installs the latest version of [black](https://github.com/psf/black) and sets it as the active version on -PATH: +The following installs the latest version of [black](https://github.com/psf/black) +and sets it as the active version on PATH: ```sh $ mise use -g pipx:psf/black @@ -42,8 +41,8 @@ The version will be set in `~/.config/mise/config.toml` with the following forma ## Python upgrades -If the python version used by a pipx package changes, (by mise or system python), you may need to reinstall the package. -This can be done with: +If the python version used by a pipx package changes, (by mise or system python), you may need to +reinstall the package. This can be done with: ```sh mise install -f pipx:psf/black @@ -82,8 +81,8 @@ import Settings from '/components/settings.vue'; ## Tool Options -The following [tool-options](/dev-tools/#tool-options) are available for the `pipx` backend—these go in `[tools]` in -`mise.toml`. +The following [tool-options](/dev-tools/#tool-options) are available for the `pipx` backend—these +go in `[tools]` in `mise.toml`. ### `extras` diff --git a/docs/dev-tools/backends/spm.md b/docs/dev-tools/backends/spm.md index d148bdb87e..15f56a3888 100644 --- a/docs/dev-tools/backends/spm.md +++ b/docs/dev-tools/backends/spm.md @@ -1,22 +1,20 @@ # SPM Backend -You may install executables managed by [Swift Package Manager](https://www.swift.org/documentation/package-manager) -directly from GitHub releases. +You may install executables managed by [Swift Package Manager](https://www.swift.org/documentation/package-manager) directly from GitHub releases. -The code for this is inside of the mise repository at -[`./src/backend/spm.rs`](https://github.com/jdx/mise/blob/main/src/backend/spm.rs). +The code for this is inside of the mise repository at [`./src/backend/spm.rs`](https://github.com/jdx/mise/blob/main/src/backend/spm.rs). ## Dependencies -This relies on having `swift` installed. You can either install it [manually](https://www.swift.org/install) or -[with mise](/lang/swift). +This relies on having `swift` installed. You can either install it [manually](https://www.swift.org/install) or [with mise](/lang/swift). -> [!NOTE] If you have Xcode installed and selected in your system via `xcode-select`, Swift is already available through -> the toolchain embedded in the Xcode installation. +> [!NOTE] +> If you have Xcode installed and selected in your system via `xcode-select`, Swift is already available through the toolchain embedded in the Xcode installation. ## Usage -The following installs the latest version of `tuist` and sets it as the active version on PATH: +The following installs the latest version of `tuist` +and sets it as the active version on PATH: ```sh $ mise use -g spm:tuist/tuist diff --git a/docs/dev-tools/backends/ubi.md b/docs/dev-tools/backends/ubi.md index f90e275684..7f3ecba889 100644 --- a/docs/dev-tools/backends/ubi.md +++ b/docs/dev-tools/backends/ubi.md @@ -1,19 +1,19 @@ # Ubi Backend -You may install GitHub Releases and URL packages directly using [ubi](https://github.com/houseabsolute/ubi) backend. ubi -is directly compiled into the mise codebase so it does not need to be installed separately to be used. ubi is preferred -over asdf/vfox for new tools since it doesn't require a plugin, supports Windows, and is really easy to use. +You may install GitHub Releases and URL packages directly using [ubi](https://github.com/houseabsolute/ubi) backend. ubi is directly compiled into +the mise codebase so it does not need to be installed separately to be used. ubi is preferred over +asdf/vfox for new tools since it doesn't require a plugin, supports Windows, and is really easy to use. -ubi doesn't require plugins or even any configuration for each tool. What it does is try to deduce what the proper -binary/tarball is from GitHub releases and downloads the right one. As long as the vendor uses a somewhat standard -labeling scheme for their releases, ubi should be able to figure it out. +ubi doesn't require plugins or even any configuration for each tool. What it does is try to deduce what +the proper binary/tarball is from GitHub releases and downloads the right one. As long as the vendor +uses a somewhat standard labeling scheme for their releases, ubi should be able to figure it out. -The code for this is inside of the mise repository at -[`./src/backend/ubi.rs`](https://github.com/jdx/mise/blob/main/src/backend/ubi.rs). +The code for this is inside of the mise repository at [`./src/backend/ubi.rs`](https://github.com/jdx/mise/blob/main/src/backend/ubi.rs). ## Usage -The following installs the latest version of goreleaser and sets it as the active version on PATH: +The following installs the latest version of goreleaser +and sets it as the active version on PATH: ```sh $ mise use -g ubi:goreleaser/goreleaser @@ -30,16 +30,16 @@ The version will be set in `~/.config/mise/config.toml` with the following forma ## Tool Options -The following [tool-options](/dev-tools/#tool-options) are available for the `ubi` backend—these go in `[tools]` in -`mise.toml`. +The following [tool-options](/dev-tools/#tool-options) are available for the `ubi` backend—these +go in `[tools]` in `mise.toml`. ### `exe` -The `exe` option allows you to specify the executable name in the archive. This is useful when the archive contains -multiple executables. +The `exe` option allows you to specify the executable name in the archive. This is useful when the +archive contains multiple executables. -If you get an error like `could not find any files named cli in the downloaded zip file`, you can use the `exe` option -to specify the executable name: +If you get an error like `could not find any files named cli in the downloaded zip file`, you can +use the `exe` option to specify the executable name: ```toml [tools] @@ -48,9 +48,10 @@ to specify the executable name: ### `matching` -Set a string to match against the release filename when there are multiple files for your OS/arch, i.e. "gnu" or "musl". -Note that this is only used when there is more than one matching release filename for your OS/arch. If only one release -asset matches your OS/arch, then this will be ignored. +Set a string to match against the release filename when there are multiple files for your +OS/arch, i.e. "gnu" or "musl". Note that this is only used when there is more than one +matching release filename for your OS/arch. If only one release asset matches your OS/arch, +then this will be ignored. ```toml [tools] @@ -61,16 +62,15 @@ asset matches your OS/arch, then this will be ignored. - **GitHub shorthand for latest release version:** `ubi:goreleaser/goreleaser` - **GitHub shorthand for specific release version:** `ubi:goreleaser/goreleaser@1.25.1` -- **URL syntax:** - `ubi:https://github.com/goreleaser/goreleaser/releases/download/v1.16.2/goreleaser_Darwin_arm64.tar.gz` +- **URL syntax:** `ubi:https://github.com/goreleaser/goreleaser/releases/download/v1.16.2/goreleaser_Darwin_arm64.tar.gz` ## Troubleshooting ubi ### `ubi` resolver can't find os/arch -Sometimes vendors use strange formats for their releases that ubi can't figure out, possibly for a specific os/arch -combination. For example this recently happend in [this ticket](https://github.com/houseabsolute/ubi/issues/79) because -a vendor used "mac" instead of the more common "macos" or "darwin" tags. +Sometimes vendors use strange formats for their releases that ubi can't figure out, possibly for a +specific os/arch combination. For example this recently happend in [this ticket](https://github.com/houseabsolute/ubi/issues/79) because a vendor used +"mac" instead of the more common "macos" or "darwin" tags. Try using ubi by itself to see if the issue is related to mise or ubi: @@ -81,8 +81,8 @@ ubi -p jdx/mise ### `ubi` picks the wrong tarball -Another issue is that a GitHub release may have a bunch of tarballs, some that don't contain the CLI you want, you can -use the `matching` field in order to specify a string to match against the release. +Another issue is that a GitHub release may have a bunch of tarballs, some that don't contain the CLI +you want, you can use the `matching` field in order to specify a string to match against the release. ```sh mise use ubi:tamasfe/taplo[matching=full] @@ -92,9 +92,9 @@ ubi -p tamasfe/taplo -m full ### `ubi` can't find the binary in the tarball -ubi assumes that the repo name is the same as the binary name, however that is often not the case. For example, -BurntSushi/ripgrep gives us a binary named `rg` not `ripgrep`. In this case, you can specify the binary name with the -`exe` field: +ubi assumes that the repo name is the same as the binary name, however that is often not the case. +For example, BurntSushi/ripgrep gives us a binary named `rg` not `ripgrep`. In this case, you can +specify the binary name with the `exe` field: ```sh mise use ubi:BurntSushi/ripgrep[exe=rg] @@ -104,15 +104,15 @@ ubi -p BurntSushi/ripgrep -e rg ### `ubi` uses weird versions -This issue is actually with mise and not with ubi. mise needs to be able to list the available versions of the tools so -that "latest" points to whatever is the actual latest release of the CLI. What sometimes happens is vendors will have -GitHub releases for unrelated things. For example, `cargo-bins/cargo-binstall` is the repo for cargo-binstall, however -it has a bunch of releases for unrelated CLIs that are not cargo-binstall. We need to filter these out and that can be -specified with the `tag_regex` tool option: +This issue is actually with mise and not with ubi. mise needs to be able to list the available versions +of the tools so that "latest" points to whatever is the actual latest release of the CLI. What sometimes +happens is vendors will have GitHub releases for unrelated things. For example, `cargo-bins/cargo-binstall` +is the repo for cargo-binstall, however it has a bunch of releases for unrelated CLIs that are not +cargo-binstall. We need to filter these out and that can be specified with the `tag_regex` tool option: ```sh mise use 'ubi:cargo-bins/cargo-binstall[tag_regex=^\d+\.]' ``` -Now when running `mise ls-remote ubi:cargo-bins/cargo-binstall[tag_regex=^\d+\.]` you should only see versions starting -with a number. Note that this command is cached so you likely will need to run `mise cache clear` first. +Now when running `mise ls-remote ubi:cargo-bins/cargo-binstall[tag_regex=^\d+\.]` you should only see +versions starting with a number. Note that this command is cached so you likely will need to run `mise cache clear` first. diff --git a/docs/dev-tools/backends/vfox.md b/docs/dev-tools/backends/vfox.md index 32b0179c78..41c1457c9b 100644 --- a/docs/dev-tools/backends/vfox.md +++ b/docs/dev-tools/backends/vfox.md @@ -2,8 +2,7 @@ [Vfox](https://github.com/version-fox/vfox) plugins may be used in mise to install tools. -The code for this is inside the mise repository at -[`./src/backend/vfox.rs`](https://github.com/jdx/mise/blob/main/src/backend/vfox.rs). +The code for this is inside the mise repository at [`./src/backend/vfox.rs`](https://github.com/jdx/mise/blob/main/src/backend/vfox.rs). ## Dependencies @@ -62,4 +61,5 @@ terraform vfox:enochchau/vfox-terraform vlang vfox:ahai-code/vfox-vlang ``` -And they will be installed when running commands such as `mise use -g cmake` without needing to specify `vfox:cmake`. +And they will be installed when running commands such as `mise use -g cmake` without needing to +specify `vfox:cmake`. diff --git a/docs/dev-tools/comparison-to-asdf.md b/docs/dev-tools/comparison-to-asdf.md index f35285f02d..81c1d62d72 100644 --- a/docs/dev-tools/comparison-to-asdf.md +++ b/docs/dev-tools/comparison-to-asdf.md @@ -1,69 +1,81 @@ # Comparison to asdf -mise can be used as a drop-in replacement for asdf. It supports the same `.tool-versions` files that you may have used -with asdf and can use asdf plugins through the [asdf backend](/dev-tools/backends/asdf.html). - -It will not, however, reuse existing asdf directories (so you'll need to either reinstall them or move them), and 100% -compatibility is not a design goal. That said, if you're coming from asdf-bash (0.15 and below), mise actually has -[fewer breaking changes than asdf-go (0.16 and above)](https://asdf-vm.com/guide/upgrading-from-v0-15-to-v0-16.html) +mise can be used as a drop-in replacement for asdf. It supports the same `.tool-versions` files that +you may have used with asdf and can use asdf plugins through +the [asdf backend](/dev-tools/backends/asdf.html). + +It will not, however, reuse existing asdf directories +(so you'll need to either reinstall them or move them), and 100% compatibility is not a design goal. +That said, +if you're coming from asdf-bash (0.15 and below), mise actually +has [fewer breaking changes than asdf-go (0.16 and above)](https://asdf-vm.com/guide/upgrading-from-v0-15-to-v0-16.html) despite 100% compatibility not being a design goal of mise. Casual users coming from asdf have generally found mise to just be a faster, easier to use asdf. -:::tip Make sure you have a look at [environments](/environments/) and [tasks](/tasks/) which are major portions of mise -that have no asdf equivalent. ::: +:::tip +Make sure you have a look at [environments](/environments/) and [tasks](/tasks/) which +are major portions of mise that have no asdf equivalent. +::: ## Migrate from asdf to mise -If you're moving from asdf to mise, please review [#how-do-i-migrate-from-asdf](/faq.html#how-do-i-migrate-from-asdf) -for guidance. +If you're moving from asdf to mise, please +review [#how-do-i-migrate-from-asdf](/faq.html#how-do-i-migrate-from-asdf) for guidance. ## asdf in go (0.16+) -asdf has gone through a rewrite in go. Because this is quite new as of this writing (2025-01-01), I'm going to keep -information about 0.16+ asdf versions (which I call "asdf-go" vs "asdf-bash") in this section and the rest of this doc -will apply to asdf-bash (0.15 and below). +asdf has gone through a rewrite in go. Because this is quite new as of this writing (2025-01-01), +I'm going to keep information about 0.16+ asdf versions (which I call "asdf-go" vs "asdf-bash") in +this section and the rest of this doc will apply to asdf-bash (0.15 and below). -In terms of performance, mise is still faster than the go asdf, however the difference is much closer. asdf is likely -fast enough that the difference in overhead between asdf-go and mise may not even be enough to notice for you—after all -there are plenty of people still using asdf-bash that claim they don't even notice how slow it is (don't ask me how): +In terms of performance, mise is still faster than the go asdf, however the difference is much +closer. asdf is likely fast enough that the difference in overhead between asdf-go and mise may not +even be enough to notice for you—after all there are plenty of people still using asdf-bash that +claim they don't even notice how slow it is (don't ask me how): ![GgAQJJmWIAAUlec](https://github.com/user-attachments/assets/05689925-396d-41f3-bcd1-7b3b1bf6c2fa) -I don't think performance is a good enough reason to switch though now that asdf-go is a thing. It's a reason, but it's -a minor one. The improved security in mise, better DX, and lack of reliance on shims are all more important than -performance. +I don't think performance is a good enough reason to switch though now that asdf-go is a thing. It's +a reason, but it's a minor one. The improved security in mise, better DX, and lack of reliance on +shims are all more important than performance. -Given they went through the trouble of rewriting asdf—that's also an indication they want to keep working on it (which -is awesome that they're doing that btw). This does mean that some of what's written here may go out of date if they -address some of the problems with asdf. +Given they went through the trouble of rewriting asdf—that's also an indication they want to keep +working on it (which is awesome that they're doing that btw). This does mean that some of what's +written here may go out of date if they address some of the problems +with asdf. ## Supply chain security -asdf plugins are not secure. This is explained in [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md), but -the quick explanation is that asdf plugins involve shell code which can essentially do anything on your machine. It's -dangerous code. What's worse is asdf plugins are rarely written by the tool vendor (who you need to trust anyway to use -the tool), which means for every asdf plugin you use you'll be trusting a random developer to not go rogue and to not -get hacked themselves and publish changes to a plugin with an exploit. +asdf plugins are not secure. This is explained +in [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md), but the quick explanation is +that asdf plugins involve shell code which can essentially do anything on your machine. It's +dangerous code. What's worse is asdf plugins are rarely written by the tool vendor (who you need to +trust anyway to use the tool), which means for every asdf plugin you use you'll be trusting a random +developer to not go rogue and to not get hacked themselves and publish changes to a plugin with an +exploit. -mise still uses asdf plugins for some tools, but we're actively reducing that count as well as moving things into the -[mise-plugins org](https://github.com/mise-plugins). It looks like asdf has a similar model with their asdf-community -org, but it isn't. asdf gives plugin authors commit access to their plugin in -[asdf-community](https://github.com/asdf-community) when they move it in, which I feel like defeats the purpose of -having a dedicated org in the first place. By the end of 2025 I would like for there to no longer be any asdf plugins in -the registry that aren't owned by me. +mise still uses asdf plugins for some tools, but we're actively reducing that count as well as +moving things into the [mise-plugins org](https://github.com/mise-plugins). It looks like asdf has a +similar model with their asdf-community org, but it isn't. asdf gives plugin authors commit access +to their plugin in [asdf-community](https://github.com/asdf-community) when they move it in, which I +feel like defeats the purpose of having a dedicated org in the first place. By the end of 2025 I +would like for there to no longer be any asdf plugins in the registry that aren't owned by me. -I've also been adopting extra security verification steps when vendors offer that ability such as gpg verification on -node installs, or slsa-verify/cosign checks on some aqua tools. +I've also been adopting extra security verification steps when vendors offer that ability such as +gpg verification on node installs, or slsa-verify/cosign checks on some aqua tools. ## UX ![CleanShot 2024-01-28 at 12 36 20@2x](https://github.com/jdx/mise-docs/assets/216188/47f381d7-1566-4b78-9260-3b85a21dd6ec) -Some commands are the same in asdf but others have been changed. Everything that's possible in asdf should be possible -in mise but may use slightly different syntax. mise has more forgiving commands, such as using fuzzy-matching, e.g.: -`mise install node@20`. While in asdf you _can_ run `asdf install node latest:20`, you can't use `latest:20` in a -`.tool-versions` file or many other places. In `mise` you can use fuzzy-matching everywhere. +Some commands are the same in asdf but others have been changed. Everything that's possible +in asdf should be possible in mise but may use slightly different syntax. mise has more forgiving +commands, +such as using fuzzy-matching, e.g.: `mise install node@20`. While in asdf you _can_ run +`asdf install node latest:20`, you can't use `latest:20` in a `.tool-versions` file or many other +places. +In `mise` you can use fuzzy-matching everywhere. asdf requires several steps to install a new runtime if the plugin isn't installed, e.g.: @@ -73,90 +85,105 @@ asdf install node latest:20 asdf local node latest:20 ``` -In `mise` this can all be done in a single step which installs the plugin, installs the runtime, and sets the version: +In `mise` this can all be done in a single step which installs the plugin, installs the runtime, +and sets the version: ```sh mise use node@20 ``` -If you have an existing `.tool-versions` file, or `.mise-toml`, you can install all plugins and runtimes with a single -command: +If you have an existing `.tool-versions` file, or `.mise-toml`, you can install all plugins +and runtimes with a single command: ```sh mise install ``` -I've found asdf to be particularly rigid and difficult to learn. It also made strange decisions like having -`asdf list all` but `asdf latest --all` (why is one a flag and one a positional argument?). `mise` makes heavy use of -aliases so you don't need to remember if it's `mise plugin add node` or `mise plugin install node`. If I can guess what -you meant, then I'll try to get mise to respond in the right way. +I've found asdf to be particularly rigid and difficult to learn. It also made strange decisions like +having `asdf list all` but `asdf latest --all` (why is one a flag and one a positional argument?). +`mise` makes heavy use of aliases so you don't need to remember if it's `mise plugin add node` or +`mise plugin install node`. If I can guess what you meant, then I'll try to get mise to respond +in the right way. -That said, there are a lot of great things about asdf. It's the best multi-runtime manager out there and I've really -been impressed with the plugin system. Most of the design decisions the authors made were very good. I really just have -2 complaints: the shims and the fact it's written in Bash. +That said, there are a lot of great things about asdf. It's the best multi-runtime manager out there +and I've really been impressed with the plugin system. Most of the design decisions the authors made +were very good. I really just have 2 complaints: the shims and the fact it's written in Bash. ## Performance -asdf made (what I consider) a poor design decision to use shims that go between a call to a runtime and the runtime -itself. e.g.: when you call `node` it will call an asdf shim file `~/.asdf/shims/node`, which then calls `asdf exec`, -which then calls the correct version of node. - -These shims have terrible performance, adding ~120ms to every runtime call. `mise activate` does not use shims and -instead updates `PATH` so that it doesn't have any overhead when simply calling binaries. These shims are the main -reason that I wrote this. Note that in the demo GIF at the top of this README that `mise` isn't actually used when -calling `node -v` for this reason. The performance is identical to running node without using mise. - -I don't think it's possible for asdf to fix these issues. The author of asdf did a great writeup of -[performance problems](https://stratus3d.com/blog/2022/08/11/asdf-performance/). asdf is written in bash which certainly -makes it challenging to be performant, however I think the real problem is the shim design. I don't think it's possible -to fix that without a complete rewrite. - -mise does call an internal command `mise hook-env` every time the directory has changed, but because it's written in -Rust, this is very quick—taking ~10ms on my machine. 4ms if there are no changes, 14ms if it's a full reload. - -tl;dr: asdf adds overhead (~120ms) when calling a runtime, mise adds a small amount of overhead (~ 5ms) when the prompt -loads. +asdf made (what I consider) a poor design decision to use shims that go between a call to a runtime +and the runtime itself. e.g.: when you call `node` it will call an asdf shim file +`~/.asdf/shims/node`, +which then calls `asdf exec`, which then calls the correct version of node. + +These shims have terrible performance, adding ~120ms to every runtime call. `mise activate` does not +use shims and instead +updates `PATH` so that it doesn't have any overhead when simply calling binaries. These shims are +the main reason that I wrote this. Note that in the demo GIF at the top of this README +that `mise` isn't actually used when calling `node -v` for this reason. The performance is +identical to running node without using mise. + +I don't think it's possible for asdf to fix these issues. The author of asdf did a great writeup +of [performance problems](https://stratus3d.com/blog/2022/08/11/asdf-performance/). asdf is written +in bash which certainly makes it challenging to be performant, however I think the real problem is +the +shim design. I don't think it's possible to fix that without a complete rewrite. + +mise does call an internal command `mise hook-env` every time the directory has changed, but because +it's written in Rust, this is very quick—taking ~10ms on my machine. 4ms if there are no changes, +14ms if it's +a full reload. + +tl;dr: asdf adds overhead (~120ms) when calling a runtime, mise adds a small amount of overhead (~ +5ms) +when the prompt loads. ## Windows support -asdf does not run on Windows at all. With mise, tools using non-asdf backends can support Windows. Of course, this means -the tool vendor must provide Windows binaries but if they do, and the backend isn't asdf, the tool should work on -Windows. +asdf does not run on Windows at all. With mise, tools using non-asdf backends can support Windows. +Of course, this means the tool +vendor must provide Windows binaries but if they do, and the backend isn't asdf, the tool should +work on Windows. ## Security -asdf plugins are insecure. They typically are written by individuals with no ties to the vendors that provide the -underlying tool. Where possible, mise does not use asdf plugins and instead uses backends like aqua and ubi which do not -require separate plugins. +asdf plugins are insecure. They typically are written by individuals with no ties to the vendors +that provide the underlying tool. +Where possible, mise does not use asdf plugins and instead uses backends like aqua and ubi which do +not require separate plugins. -Aqua tools can be configured with cosign/slsa verification as well. See -[SECURITY](https://github.com/jdx/mise/blob/main/SECURITY.md) for more information. +Aqua tools can be configured with cosign/slsa verification as well. +See [SECURITY](https://github.com/jdx/mise/blob/main/SECURITY.md) for more information. ## Command Compatibility -In nearly all places you can use the exact syntax that works in asdf, however this likely won't show up in the help or -CLI reference. If you're coming from asdf and comfortable with that way of working you can almost always use the same -syntax with mise, e.g.: +In nearly all places you can use the exact syntax that works in asdf, however this likely won't +show up in the help or CLI reference. If you're coming from asdf and comfortable with that way of +working you can almost always use the same syntax with mise, e.g.: ```sh mise install node 20.0.0 mise local node 20.0.0 ``` -UPDATE (2025-01-01): asdf-go (0.16+) actually got rid of `asdf global|local` entirely in favor of `asdf set` which we -can't support since we already have a command named `mise set`. mise command compatibility will likely not be as good -with asdf-go 0.16+. +UPDATE (2025-01-01): asdf-go (0.16+) actually got rid of `asdf global|local` entirely in favor of +`asdf set` which we can't support since we already have a command named `mise set`. mise command +compatibility will likely not be as good with asdf-go 0.16+. -It's not recommended though. You almost always want to modify config files and install things so `mise use node@20` -saves an extra command. Also, the "@" in the command is preferred since it allows you to install multiple tools at once: -`mise use|install node@20 node@18`. Also, there are edge cases where it's not possible—or at least very challenging—for -us to definitively know which syntax is being used and so we default to mise-style. While there aren't many of these, -asdf-compatibility is done as a "best-effort" in order to make transitioning from asdf feel familiar for those users who -can rely on their muscle memory. Ensuring asdf-syntax works with everything is not a design goal. +It's not recommended though. You almost always want to modify config files and install things so +`mise use node@20` saves an extra command. Also, the "@" in the command is preferred since it allows +you to install multiple tools at once: `mise use|install node@20 node@18`. Also, there are edge +cases +where it's not possible—or at least very challenging—for us to definitively know which syntax is +being +used and so we default to mise-style. While there aren't many of these, asdf-compatibility is done +as a "best-effort" in order to make transitioning from asdf feel familiar for those users who can +rely on their muscle memory. Ensuring asdf-syntax works with everything is not a design goal. ## Extra backends -mise has support for backends other than asdf plugins. For example you can install CLIs directly from cargo and npm: +mise has support for backends other than asdf plugins. For example you can install CLIs +directly from cargo and npm: ```sh mise use -g cargo:ripgrep@14 diff --git a/docs/dev-tools/index.md b/docs/dev-tools/index.md index 9c64bbeaea..3008659fea 100644 --- a/docs/dev-tools/index.md +++ b/docs/dev-tools/index.md @@ -1,21 +1,20 @@ # Dev Tools -> _Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm) or [pyenv](https://github.com/pyenv/pyenv) -> but for any language), it manages dev tools like node, python, cmake, terraform, and [hundreds more](/registry.html)._ +> _Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm) +> or [pyenv](https://github.com/pyenv/pyenv) but for any language), it manages dev tools like node, +> python, cmake, terraform, and [hundreds more](/registry.html)._ -::: tip New developer? Try reading the [Beginner's Guide](https://dev.to/jdxcode/beginners-guide-to-rtx-ac4) for a -gentler introduction. ::: +::: tip +New developer? Try reading the [Beginner's Guide](https://dev.to/jdxcode/beginners-guide-to-rtx-ac4) +for a gentler introduction. +::: -mise is a tool that manages installations of programming language runtimes and other tools for local development. For -example, it can be used to manage multiple versions of Node.js, Python, Ruby, Go, etc. on the same machine. +mise is a tool that manages installations of programming language runtimes and other tools for local development. For example, it can be used to manage multiple versions of Node.js, Python, Ruby, Go, etc. on the same machine. -Once [activated](/getting-started.html#_2-activate-mise), mise will automatically switch between different versions of -tools based on the directory you're in. This means that if you have a project that requires Node.js 18 and another that -requires Node.js 22, mise will automatically switch between them as you move between the two projects. See tools -available for mise with in the [registry](/registry). +Once [activated](/getting-started.html#_2-activate-mise), mise will automatically switch between different versions of tools based on the directory you're in. +This means that if you have a project that requires Node.js 18 and another that requires Node.js 22, mise will automatically switch between them as you move between the two projects. See tools available for mise with in the [registry](/registry). -To know which tool version to use, mise will typically look for a `mise.toml` file in the current directory and its -parents. To get an idea of how tools are specified, here is an example of a [mise.toml](/configuration.html) file: +To know which tool version to use, mise will typically look for a `mise.toml` file in the current directory and its parents. To get an idea of how tools are specified, here is an example of a [mise.toml](/configuration.html) file: ```toml [tools] @@ -24,36 +23,43 @@ python = '3' ruby = 'latest' ``` -It's also compatible with asdf `.tool-versions` files as well as -[idiomatic version files](/configuration#idiomatic-version-files) like `.node-version` and `.ruby-version`. See -[configuration](/configuration) for more details. +It's also compatible +with asdf `.tool-versions` files as well as [idiomatic version files](/configuration#idiomatic-version-files) like `.node-version` and +`.ruby-version`. See [configuration](/configuration) for more details. -::: info mise is inspired by [asdf](https://asdf-vm.com) and can leverage asdf's vast -[plugin ecosystem](https://github.com/mise-plugins/registry) under the hood. However, -[it is _much_ faster than asdf and has a more friendly user experience](./comparison-to-asdf). ::: +::: info +mise is inspired by [asdf](https://asdf-vm.com) and can leverage asdf's +vast [plugin ecosystem](https://github.com/mise-plugins/registry) +under the hood. However, [it is _much_ faster than asdf and has a more friendly user experience](./comparison-to-asdf). +::: ## How it works -mise hooks into your shell (with `mise activate zsh`) and sets the `PATH` environment variable to point your shell to -the correct runtime binaries. When you `cd` into a directory containing a `mise.toml`/`.tool-versions` file, mise will -automatically set the appropriate tool versions in `PATH`. +mise hooks into your shell (with `mise activate zsh`) and sets the `PATH` +environment variable to point your shell to the correct runtime binaries. When you `cd` into a +directory containing a `mise.toml`/`.tool-versions` file, mise will automatically set the +appropriate tool versions in `PATH`. -::: info After activating, mise will update env vars like PATH whenever the directory is changed or the prompt is -_displayed_. See the [FAQ](/faq#what-does-mise-activate-do). ::: +::: info +After activating, mise will update env vars like PATH whenever the directory is changed or the prompt is _displayed_. +See the [FAQ](/faq#what-does-mise-activate-do). +::: -After activating, every time your prompt displays it will call `mise hook-env` to fetch new environment variables. This -should be very fast. It exits early if the directory wasn't changed or `mise.toml`/`.tool-versions` files haven't been -modified. +After activating, every time your prompt displays it will call `mise hook-env` to fetch new +environment variables. +This should be very fast. It exits early if the directory wasn't changed or +`mise.toml`/`.tool-versions` files haven't been modified. -`mise` modifies `PATH` ahead of time so the runtimes are called directly. This means that calling a tool has zero -overhead and commands like `which node` returns the real path to the binary. Other tools like asdf only support shim -files to dynamically locate runtimes when they're called which adds a small delay and can cause issues with some -commands. See [shims](/dev-tools/shims) for more information. +`mise` modifies `PATH` ahead of time so the runtimes are called directly. This means that calling a tool has zero overhead and commands like `which node` returns the real path to the binary. +Other tools like asdf only support shim files to dynamically locate runtimes when they're called which adds a small delay and can cause issues with some commands. See [shims](/dev-tools/shims) for more information. ## Common commands -Here are some of the most important commands when it comes to working with dev tools. Click the header for each command -to go to its reference documentation page to see all available flags/options and more examples. +Here are some of the most important commands when it comes to working with dev tools. Click the +header +for each command to go to its reference documentation page to see all available flags/options and +more +examples. ### [`mise use`](/cli/use) @@ -75,40 +81,50 @@ mise ~/my-project/mise.toml tools: node@22.12.0 # mise.toml created/updated ~/.local/share/installs/node/22.12.0/bin/node ``` -`mise use node@22` will install the latest version of node-22 and create/update the `mise.toml` config file in the local -directory. Anytime you're in that directory, that version of `node` will be used. +`mise use node@22` will install the latest version of node-22 and create/update the +`mise.toml` +config file in the local directory. Anytime you're in that directory, that version of `node` will be +used. -`mise use -g node@22` will do the same but update the -[global config](/configuration.html#global-config-config-mise-config-toml) (~/.config/mise/config.toml) so unless there -is a config file in the local directory hierarchy, node-22 will be the default version for the user. +`mise use -g node@22` will do the same but update the [global config](/configuration.html#global-config-config-mise-config-toml) (~/.config/mise/config.toml) so +unless there is a config file in the local directory hierarchy, node-22 will be the default version +for +the user. ### [`mise install`](/cli/install) -`mise install` will install but not activate tools—meaning it will download/build/compile the tool into -`~/.local/share/mise/installs` but you won't be able to use it without "setting" the version in a `.mise-toml` or -`.tool-versions` file. +`mise install` will install but not activate tools—meaning it will download/build/compile the tool +into `~/.local/share/mise/installs` but you won't be able to use it without "setting" the version +in a `.mise-toml` or `.tool-versions` file. -::: tip If you're coming from `asdf`, there is no need to also run `mise plugin add` to first install the plugin, that -will be done automatically if needed. Of course, you can manually install plugins if you wish or you want to use a -plugin not in the default registry. ::: +::: tip +If you're coming from `asdf`, there is no need to also run `mise plugin add` to first install +the plugin, that will be done automatically if needed. Of course, you can manually install plugins +if you wish or you want to use a plugin not in the default registry. +::: There are many ways it can be used: - `mise install node@20.0.0` - install a specific version - `mise install node@20` - install the latest version matching this prefix -- `mise install node` - install whatever version of node currently specified in `mise.toml` (or other config files) +- `mise install node` - install whatever version of node currently specified in `mise.toml` (or other + config files) - `mise install` - install all plugins and tools specified in the config files ### [`mise exec`|`mise x`](/cli/exec) -`mise x` can be used for one-off commands using specific tools. e.g.: if you want to run a script with python3.12: +`mise x` can be used for one-off commands using specific tools. e.g.: if you want to run a script +with python3.12: ```sh mise x python@3.12 -- ./myscript.py ``` -Python will be installed if it is not already. `mise x` will read local/global `.mise-toml`/`.tool-versions` files as -well, so if you don't want to use `mise activate` or shims you can use mise by just prefixing commands with `mise x --`: +Python will be installed if it is not already. `mise x` will read local/global +`.mise-toml`/`.tool-versions` files +as well, so if you don't want to use `mise activate` or shims you can use mise by just prefixing +commands with +`mise x --`: ```sh $ mise use node@20 @@ -116,7 +132,8 @@ $ mise x -- node -v 20.x.x ``` -::: tip If you use this a lot, an alias can be helpful: +::: tip +If you use this a lot, an alias can be helpful: ```sh alias mx="mise x --" @@ -124,8 +141,8 @@ alias mx="mise x --" ::: -Similarly, `mise run` can be used to [execute tasks](/tasks/) which will also activate the mise environment with all of -your tools. +Similarly, `mise run` can be used to [execute tasks](/tasks/) which will also activate the mise +environment with all of your tools. ## Tool Options @@ -145,8 +162,7 @@ All tools can accept a `postinstall` option which is a shell command to run afte node = { version = '20', postinstall = 'corepack enable' } ``` -It's yet not possible to specify this via the CLI in `mise use`. As a workaround, you can use -[mise config set](/cli/config/set.html): +It's yet not possible to specify this via the CLI in `mise use`. As a workaround, you can use [mise config set](/cli/config/set.html): ```shell mise config set tools.node.version 20 diff --git a/docs/dev-tools/shims.md b/docs/dev-tools/shims.md index 8a4baa868d..67c9f2e0fd 100644 --- a/docs/dev-tools/shims.md +++ b/docs/dev-tools/shims.md @@ -1,11 +1,13 @@ # Shims -::: tip The [beginner's guide](https://dev.to/jdxcode/beginners-guide-to-rtx-ac4), and my -[blog post](https://jdx.dev/posts/2024-04-13-shims-how-they-work-in-mise-en-place/) are helpful resources to dive deeper -into shims. ::: +::: tip +The [beginner's guide](https://dev.to/jdxcode/beginners-guide-to-rtx-ac4), and my [blog post](https://jdx.dev/posts/2024-04-13-shims-how-they-work-in-mise-en-place/) are helpful resources to dive deeper into shims. +::: -::: warning `mise activate --shims` does not support all the features of `mise activate`.
See -[shims vs path](/dev-tools/shims.html#shims-vs-path) for more info. ::: +::: warning +`mise activate --shims` does not support all the features of `mise activate`.
+See [shims vs path](/dev-tools/shims.html#shims-vs-path) for more info. +::: ## Introduction @@ -14,8 +16,8 @@ There are two ways for dev tools to be loaded into your shell: `mise activate` a - Mise's "PATH" activation method updates environment variables at each prompt by modifying `PATH` - The "shims" method uses symlinks to the mise binary that intercept commands and load the appropriate environment -While the `PATH` design of mise works great in most cases, there are some situations where shims are preferable. One -example is when calling mise binaries from an IDE. +While the `PATH` design of mise works great in most cases, there are some situations where shims are +preferable. One example is when calling mise binaries from an IDE. To support this, mise does have a shim dir that can be used. It's located at `~/.local/share/mise/shims`. @@ -29,25 +31,29 @@ $ ~/.local/share/mise/shims/prettier -v 3.1.0 ``` -::: tip `mise activate --shims` is a shorthand for adding the shims directory to PATH. ::: +::: tip +`mise activate --shims` is a shorthand for adding the shims directory to PATH. +::: -::: info `mise reshim` actually should get called automatically if you're using npm so an explicit reshim should not be -necessary in that scenario. Also, this bears repeating but: `mise reshim` just creates/removes the shims. People use it -as a "fix it" button but it really should only be necessary if `~/.local/share/mise/shims` doesn't contain something it -should. +::: info +`mise reshim` actually should get called automatically if you're using npm so an explicit reshim should not be necessary +in that scenario. Also, this bears repeating but: `mise reshim` just creates/removes the shims. People use it as a +"fix it" button but it really should only be necessary if `~/.local/share/mise/shims` doesn't contain something it should. mise also runs a reshim anytime a tool is installed/updated/removed so you don't need to use it for those scenarios. -Also don't put things in there manually, mise will just delete it next reshim. ::: +Also don't put things in there manually, mise will just delete it next reshim. +::: ## How to add mise shims to PATH If you prefer to use shims, you can run the following to use mise without activating it. -You can use `.bashrc`/`.zshrc` instead of `.bash_profile`/`.zprofile` if you prefer to only use mise in interactive -sessions (`.bash_profile`/`.zprofile` will work in non-interactive places like scripts or IDEs). Note that -`mise activate` will remove the shims directory so it's fine to call `mise activate --shims` in the profile file then -later call `mise activate` in an interactive session. +You can use `.bashrc`/`.zshrc` instead of `.bash_profile`/`.zprofile` if you prefer to only use +mise in interactive sessions (`.bash_profile`/`.zprofile` will work in non-interactive places +like scripts or IDEs). Note that `mise activate` will remove the shims directory so it's fine +to call `mise activate --shims` in the profile file then later call `mise activate` in an interactive +session. ::: code-group @@ -68,9 +74,11 @@ echo 'mise activate fish --shims | source' >> ~/.config/fish/config.fish echo 'mise activate fish | source' >> ~/.config/fish/fish.config ``` -:::tip You can also run `export PATH="$HOME/.local/share/mise/shims:$PATH"` which is what `mise activate --shims` does. -This can be helpful is mise may not be available at that point in time. It's also a tiny bit faster, but since this is -only run once per shell session it's not a big deal. ::: +:::tip +You can also run `export PATH="$HOME/.local/share/mise/shims:$PATH"` which is what `mise activate --shims` does. +This can be helpful is mise may not be available at that point in time. It's also a tiny bit faster, +but since this is only run once per shell session it's not a big deal. +::: ## Shims vs PATH @@ -80,10 +88,11 @@ The following features are affected when shims are used **instead** of PATH acti - Most hooks won't trigger - The unix `which` command points to the shim, obscuring the real executable -In general, I recommend using PATH (`mise activate`) instead of shims for _interactive_ situations. The way activate -works is every time the prompt is displayed, mise-en-place will determine what PATH and other env vars should be and -export them. This is why it doesn't work well for non-interactive situations like scripts. The prompt never gets -displayed so you have to manually call `mise hook-env` to get mise to update the env vars. +In general, I recommend using PATH (`mise activate`) instead of shims for _interactive_ situations. The +way activate works is every time the prompt is displayed, mise-en-place will determine what PATH and other +env vars should be and export them. This is why it doesn't work well for non-interactive situations like +scripts. The prompt never gets displayed so you have to manually call `mise hook-env` to get mise to update +the env vars. Also, if you run a set of commands in a single line like the following: @@ -92,21 +101,24 @@ cd ~ cd ~/src/proj1 && node -v && cd ~/src/proj2 && node -v ``` -Using `mise activate`, this will use the tools from `~`, not from `~/src/proj1` or `~/src/proj2` even after the -directory changed because the prompt never got displayed. That might be obvious to you, not sure, what I'm trying to -convey though is just think of mise running just before your prompt gets displayed—because that literally is what is -happening. It's not a magical utility that is capable of having your environment always setup perfectly in every -situation even though it might normally "feel" that way. +Using `mise activate`, this will use the tools from `~`, not from `~/src/proj1` or `~/src/proj2` even +after the directory changed because the prompt never got displayed. That might be obvious to you, not sure, +what I'm trying to convey though is just think of mise running just before your prompt gets displayed—because +that literally is what is happening. It's not a magical utility that is capable of having your environment +always setup perfectly in every situation even though it might normally "feel" that way. Note that shims _will_ work with the inline example above. -::: info This may be fixable at least for some shells if they support a hook for directory change, however some -investigation will need to be done. See [#1294](https://github.com/jdx/mise/issues/1294) for details. ::: +::: info +This may be fixable at least for some shells if they support a hook for directory change, however +some investigation will need to be done. See [#1294](https://github.com/jdx/mise/issues/1294) for details. +::: ### Env vars and shims -A downside of shims is the "mise environment" is only loaded when a shim is called. This means if you set an environment -variable in `mise.toml`, it will only be run when a shim is called. So the following only works under `mise activate`: +A downside of shims is the "mise environment" is only loaded when a shim is called. This means if you +set an environment variable in `mise.toml`, it will only be run when a shim is called. So the following +only works under `mise activate`: ```sh $ mise set NODE_ENV=production @@ -122,7 +134,8 @@ $ node -p process.env.NODE_ENV production ``` -Also, `mise x|exec` and `mise r|run` can be used to get the environment even if you don't need any mise tools: +Also, `mise x|exec` and `mise r|run` can be used to get the environment even if you don't need any mise +tools: ```sh $ mise set NODE_ENV=production @@ -132,19 +145,21 @@ $ mise r some_task_that_uses_NODE_ENV production ``` -::: tip In general, [tasks](/tasks/) are a good way to ensure that the mise environment is always loaded so this isn't a -problem. ::: +::: tip +In general, [tasks](/tasks/) are a good way to ensure that the mise environment is always loaded so +this isn't a problem. +::: ### Hooks and shims -The [hooks](/hooks.html) `cd`, `enter`, `exit`, and `watch_files` only trigger with `mise activate`. However -`preinstall` and `postinstall` still work with shims because they don't require shell integration. +The [hooks](/hooks.html) `cd`, `enter`, `exit`, and `watch_files` only trigger with `mise activate`. However `preinstall` and `postinstall` still work with shims because they don't require shell integration. ### `which` -`which` is a command that I personally find great value in. shims effectively "break" `which` and cause it to show the -location of the shim. Of course `mise which` will show the location but I prefer the "cleanliness" of running -`which node` and getting back a real path with a version number inside of it. e.g: +`which` is a command that I personally find great value in. shims effectively "break" `which` and +cause it to show the location of the shim. Of course `mise which` will show the location but I prefer +the "cleanliness" of running `which node` and getting back a real path with a version number inside of it. +e.g: ```sh $ which node @@ -153,17 +168,17 @@ $ which node ## Hook on `cd` -Some version managers modify the behavior of `cd`. That might seem like the ideal method of making a version manager, it -has tons of gaps. It doesn't work if you use `pushd|popd` or other commands that modify PWD—though some shells have a -"chpwd" hook that would. It doesn't run if you modify the `mise.toml` file. +Some version managers modify the behavior of `cd`. That might seem like the ideal method of making a version +manager, it has tons of gaps. It doesn't work if you use `pushd|popd` or other commands that modify PWD—though +some shells have a "chpwd" hook that would. It doesn't run if you modify the `mise.toml` file. -The upside is that it doesn't run as frequently but since mise is written in rust the cost for executing mise is -negligible (~4-5ms). +The upside is that it doesn't run as frequently but since mise is written in rust the cost for executing +mise is negligible (~4-5ms). ## .zshrc/.bashrc files -rc files like `.zshrc` are unusual. It's a script but also runs only for interactive sessions. If you need to access -tools provided by mise inside of an rc file you have 2 options: +rc files like `.zshrc` are unusual. It's a script but also runs only for interactive sessions. If you need +to access tools provided by mise inside of an rc file you have 2 options: ::: code-group @@ -181,23 +196,23 @@ node some_script.js ::: -The only difference I can think of between these would be that using `hook-env` you will need to call it again if you -change directories but with shims that won't be necessary. The shims directory will be removed by `mise activate` -automatically so you won't need to worry about dealing with shims in your PATH. +The only difference I can think of between these would be that using `hook-env` you will need to call +it again if you change directories but with shims that won't be necessary. The shims directory will be +removed by `mise activate` automatically so you won't need to worry about dealing with shims in your PATH. ## Performance -Truthfully, you're probably not going to notice much in the way of performance with any solution here. However, I would -like to document what the tradeoffs are since it's not as simple as "shims are slow". In asdf they are, but that's -because asdf is written in bash. In mise the cost of the shims are negligible. +Truthfully, you're probably not going to notice much in the way of performance with any solution here. +However, I would like to document what the tradeoffs are since it's not as simple as "shims are slow". +In asdf they are, but that's because asdf is written in bash. In mise the cost of the shims are negligible. -First, since mise runs every time the prompt is displayed with `mise activate`, you'll pay a few ms cost every time the -prompt is displayed. Regardless of whether or not you're actively using a mise tool, you'll pay that penalty every time -you run any command. It does have some short-circuiting logic to make it faster if there are no changes but it doesn't -help much unless you have a very complex setup. +First, since mise runs every time the prompt is displayed with `mise activate`, you'll pay a few ms cost +every time the prompt is displayed. Regardless of whether or not you're actively using a mise tool, you'll +pay that penalty every time you run any command. It does have some short-circuiting logic to make it faster +if there are no changes but it doesn't help much unless you have a very complex setup. -shims have basically the same performance profile but run when the shim is called. This makes some situations better, -and some worse. +shims have basically the same performance profile but run when the shim is called. This makes some situations +better, and some worse. If you are calling a shim from within a bash script like this: @@ -207,29 +222,31 @@ for i in {1..500}; do done ``` -You'll pay the mise penalty every time you call it within the loop. However, if you did the same thing but call a -subprocess from within a shim (say, node creating a node subprocess), you will _not_ pay a new penalty. This is because -when a shim is called, mise sets up the environment with PATH for all tools and those PATH entries will be before the -shim directory. +You'll pay the mise penalty every time you call it within the loop. However, if you did the same thing +but call a subprocess from within a shim (say, node creating a node subprocess), you will _not_ pay a new +penalty. This is because when a shim is called, mise sets up the environment with PATH for all tools and +those PATH entries will be before the shim directory. -In other words, which is better in terms of performance just depends on how you're calling mise. Really though I think -most users won't notice a 5ms lag on their terminal so I suggest `mise activate`. +In other words, which is better in terms of performance just depends on how you're calling mise. Really +though I think most users won't notice a 5ms lag on their terminal so I suggest `mise activate`. ## Neither shims nor PATH -[I don't actually use either of these methods](https://mise.jdx.dev/how-i-use-mise.html). There are many ways to load -the mise environment that don't require either, chiefly: `mise x|exec` and `mise r|run`. +[I don't actually use either of these methods](https://mise.jdx.dev/how-i-use-mise.html). There are many +ways to load the mise environment that don't require either, chiefly: `mise x|exec` and `mise r|run`. -These will both load all of the tools and env vars before executing something. I find this to be ideal because I don't -need to modify my shell rc file at all and my environment is always loaded explicitly. I find this a "clean" way of -working. +These will both load all of the tools and env vars before executing something. I find this to be +ideal because I don't need to modify my shell rc file at all and my environment is always loaded +explicitly. I find this a "clean" way of working. -The obvious downside is that anytime I want to use `mise` I need to prefix it with `mise exec|run`, though I alias them -to `mx|mr`. +The obvious downside is that anytime I want to use `mise` I need to prefix it with `mise exec|run`, +though I alias them to `mx|mr`. -This is what I'd recommend if you're like me and prefer things to be precise over "easy". Or perhaps if you're just -wanting to use mise on a single project because that's what your team uses and prefer not to use it to manage anything -else on your system. IMO using a shell extension for that use-case would be overkill. +This is what I'd recommend if you're like me and prefer things to be precise over "easy". Or perhaps +if you're just wanting to use mise on a single project because that's what your team uses and prefer +not to use it to manage anything else on your system. IMO using a shell extension for that use-case +would be overkill. -Part of the reason for this is I often need to make sure I'm on my development version of mise. If you work on mise -yourself I would recommend working in a similar way and disabling `mise activate` or shims while you are working on it. +Part of the reason for this is I often need to make sure I'm on my development version of mise. If you +work on mise yourself I would recommend working in a similar way and disabling `mise activate` or shims +while you are working on it. diff --git a/docs/directories.md b/docs/directories.md index 9737e2fcd3..497cf68546 100644 --- a/docs/directories.md +++ b/docs/directories.md @@ -2,8 +2,9 @@ The following are the directories that mise uses. -::: tip If you often find yourself using these directories (as I do), I suggest setting all of them to `~/.mise` for -easy access. ::: +::: tip +If you often find yourself using these directories (as I do), I suggest setting all of them to `~/.mise` for easy access. +::: ## `~/.config/mise` @@ -18,9 +19,10 @@ dotfiles repo to share across machines. - Override: `$MISE_CACHE_DIR` - Default: `${XDG_CACHE_HOME:-$HOME/.cache}/mise`, _macOS: `~/Library/Caches/mise`._ -Stores internal cache that mise uses for things like the list of all available versions of a plugin. Do not share this -across machines. You may delete this directory any time mise isn't actively installing something. Do this with -`mise cache clear`. See [Cache Behavior](/cache-behavior) for more information. +Stores internal cache that mise uses for things like the list of all available versions of a +plugin. Do not share this across machines. You may delete this directory any time mise isn't actively installing something. +Do this with `mise cache clear`. +See [Cache Behavior](/cache-behavior) for more information. ## `~/.local/state/mise` @@ -35,21 +37,23 @@ machines. - Override: `$MISE_DATA_DIR` - Default: `${XDG_DATA_HOME:-$HOME/.local/share}/mise` -This is the main directory that mise uses and is where plugins and tools are installed into. It is nearly identical to -`~/.asdf` in asdf, so much so that you may be able to get by symlinking these together and using asdf and mise -simultaneously. (Supporting this isn't a project goal, however). +This is the main directory that mise uses and is where plugins and tools are installed into. +It is nearly identical to `~/.asdf` in asdf, so much so that you may be able to get by +symlinking these together and using asdf and mise simultaneously. (Supporting this isn't a +project goal, however). This directory _could_ be shared across machines but only if they run the same OS/arch. In general I wouldn't advise doing so. ### `~/.local/share/mise/downloads` -This is where plugins may optionally cache downloaded assets such as tarballs. Use the `always_keep_downloads` setting -to prevent mise from removing files from here. +This is where plugins may optionally cache downloaded assets such as tarballs. Use the +`always_keep_downloads` setting to prevent mise from removing files from here. ### `~/.local/share/mise/plugins` -mise installs plugins to this directory when running `mise plugins install`. If you are working on a plugin, I suggest +mise installs plugins to this directory when running `mise plugins install`. If you are working on a +plugin, I suggest symlinking it manually by running: ```sh @@ -58,11 +62,12 @@ ln -s ~/src/mise-my-tool ~/.local/share/mise/plugins/my-tool ### `~/.local/share/mise/installs` -This is where tools are installed to when running `mise install`. For example, `mise install node@20.0.0` will install -to `~/.local/share/mise/installs/node/20.0.0` +This is where tools are installed to when running `mise install`. For example, `mise install +node@20.0.0` will install to `~/.local/share/mise/installs/node/20.0.0` -This will also create other symlinks to this directory for version prefixes ("20" and "20.15") and matching aliases -("lts", "latest"). For example: +This will also create other symlinks to this directory for version prefixes ("20" and "20.15") +and matching aliases ("lts", "latest"). +For example: ```sh $ tree ~/.local/share/mise/installs/node @@ -74,5 +79,5 @@ latest -> ./20.15.0 ### `~/.local/share/mise/shims` -This is where mise places shims. Generally these are used for IDE integration or if `mise activate` does not work for -some reason. +This is where mise places shims. Generally these are used for IDE integration or if `mise activate` +does not work for some reason. diff --git a/docs/direnv.md b/docs/direnv.md index 7d77b25bec..1aef158193 100644 --- a/docs/direnv.md +++ b/docs/direnv.md @@ -1,31 +1,43 @@ # direnv -[direnv](https://direnv.net) and mise both manage environment variables based on directory. Because they both analyze -the current environment variables before and after their respective "hook" commands are run, they can sometimes conflict -with each other. - -::: warning The official stance is you should not use direnv with mise. Issues arising from incompatibilities are not -considered bugs. If mise has feature gaps that direnv resolves, please open an issue so we can close those gaps. While -that's the official stance, the reality is mise and direnv usually will work together just fine despite this. It's only -more advanced use-cases where problems arise. ::: - -If you have an issue, it's likely to do with the ordering of PATH. This means it would really only be a problem if you -were trying to manage the same tool with direnv and mise. For example, you may use `layout python` in an `.envrc` but -also be maintaining a `.tool-versions` file with python in it as well. - -A more typical usage of direnv would be to set some arbitrary environment variables, or add unrelated binaries to PATH. -In these cases, mise will not interfere with direnv. +[direnv](https://direnv.net) and mise both manage environment variables based on directory. Because +they both analyze +the current environment variables before and after their respective "hook" commands are run, they +can sometimes conflict with each other. + +::: warning +The official stance is you should not use direnv with mise. Issues arising +from incompatibilities are not considered bugs. If mise has feature gaps +that direnv resolves, please open an issue so we can close those gaps. +While that's the official stance, the reality is mise and direnv usually +will work together just fine despite this. It's only more advanced use-cases +where problems arise. +::: + +If you have an issue, it's likely to do with the ordering of PATH. This means it would +really only be a problem if you were trying to manage the same tool with direnv and mise. For +example, +you may use `layout python` in an `.envrc` but also be maintaining a `.tool-versions` file with +python +in it as well. + +A more typical usage of direnv would be to set some arbitrary environment variables, or add +unrelated +binaries to PATH. In these cases, mise will not interfere with direnv. ## mise inside of direnv (`use mise` in `.envrc`) -::: warning `use mise` is deprecated and no longer supported. If `mise activate` does not fit your use-case please post -an issue. ::: +::: warning +`use mise` is deprecated and no longer supported. If `mise activate` does +not fit your use-case please post an issue. +::: -If you do encounter issues with `mise activate`, or just want to use direnv in an alternate way, this is a simpler setup -that's less likely to cause issues—at the cost of functionality. +If you do encounter issues with `mise activate`, or just want to use direnv in an alternate way, +this is a simpler setup that's less likely to cause issues—at the cost of functionality. -This may be required if you want to use direnv's `layout python` with mise. Otherwise there are situations where mise -will override direnv's PATH. `use mise` ensures that direnv always has control. +This may be required if you want to use direnv's `layout python` with mise. Otherwise there are +situations where mise will override direnv's PATH. `use mise` ensures that direnv always has +control. To do this, first use `mise` to build a `use_mise` function that you can use in `.envrc` files: @@ -39,27 +51,32 @@ Now in your `.envrc` file add the following: use mise ``` -direnv will now call mise to export its environment variables. You'll need to make sure to add `use_mise` to all -projects that use mise (or use direnv's `source_up` to load it from a subdirectory). You can also add `use mise` to -`~/.config/direnv/direnvrc`. +direnv will now call mise to export its environment variables. You'll need to make sure to +add `use_mise` +to all projects that use mise (or use direnv's `source_up` to load it from a subdirectory). You can +also add `use mise` to `~/.config/direnv/direnvrc`. -Note that in this method direnv typically won't know to refresh `.tool-versions` files unless they're at the same level -as a `.envrc` file. You'll likely always want to have a `.envrc` file next to your `.tool-versions` for this reason. To -make this a little easier to manage, I encourage _not_ actually using `.tool-versions` at all, and instead setting -environment variables entirely in `.envrc`: +Note that in this method direnv typically won't know to refresh `.tool-versions` files +unless they're at the same level as a `.envrc` file. You'll likely always want to have +a `.envrc` file next to your `.tool-versions` for this reason. To make this a little +easier to manage, I encourage _not_ actually using `.tool-versions` at all, and instead +setting environment variables entirely in `.envrc`: ```sh export MISE_NODE_VERSION=20.0.0 export MISE_PYTHON_VERSION=3.11 ``` -Of course if you use `mise activate`, then these steps won't have been necessary and you can use mise as if direnv was -not used. +Of course if you use `mise activate`, then these steps won't have been necessary and you can use +mise +as if direnv was not used. If you continue to struggle, you can also try using the [shims method](dev-tools/shims.md). ### Do you need direnv? -While making mise compatible with direnv is, and will always be a major goal of this project, I also want mise to be -capable of replacing direnv if needed. This is why mise includes support for managing env vars and -[virtualenv](lang/python.md#automatic-virtualenv-activation) for python using `mise.toml`. +While making mise compatible with direnv is, and will always be a major goal of this project, I also +want mise to be capable of replacing direnv if needed. This is why mise includes support for +managing +env vars and [virtualenv](lang/python.md#automatic-virtualenv-activation) +for python using `mise.toml`. diff --git a/docs/environments/index.md b/docs/environments/index.md index c89cc04c9b..40ad405611 100644 --- a/docs/environments/index.md +++ b/docs/environments/index.md @@ -1,9 +1,11 @@ # Environments -> Like [direnv](https://github.com/direnv/direnv) it manages _environment variables_ for different project directories. +> Like [direnv](https://github.com/direnv/direnv) it +> manages _environment variables_ for +> different project directories. -Use mise to specify environment variables used for different projects. Create a `mise.toml` file in the root of your -project directory: +Use mise to specify environment variables used for different projects. Create a `mise.toml` file +in the root of your project directory: ```toml [env] @@ -31,9 +33,9 @@ $ mise unset NODE_ENV ## Lazy eval -Environment variables typically are resolved before tools—that way you can configure tool installation with environment -variables. However, sometimes you want to access environment variables produced by tools. To do that, turn the value -into a map with `tools = true`: +Environment variables typically are resolved before tools—that way you can configure tool installation +with environment variables. However, sometimes you want to access environment variables produced by +tools. To do that, turn the value into a map with `tools = true`: ```toml [env] @@ -53,25 +55,29 @@ _.file = { path = [".env.json"], redact = true } ## `env._` directives -`env._.*` define special behavior for setting environment variables. (e.g.: reading env vars from a file). Since nested -environment variables do not make sense, we make use of this fact by creating a key named "\_" which is a TOML table for -the configuration of these directives. +`env._.*` define special behavior for setting environment variables. (e.g.: reading env vars +from a file). Since nested environment variables do not make sense, +we make use of this fact by creating a key named "\_" which is a +TOML table for the configuration of these directives. ### `env._.file` -In `mise.toml`: `env._.file` can be used to specify a [dotenv](https://dotenv.org) file to load. It can be a string or -array and uses relative or absolute paths: +In `mise.toml`: `env._.file` can be used to specify a [dotenv](https://dotenv.org) file to load. +It can be a string or array and uses relative or absolute paths: ```toml [env] _.file = '.env' ``` -::: info This uses [dotenvy](https://crates.io/crates/dotenvy) under the hood. If you have problems with the way -`env._.file` works, you will likely need to post an issue there, not to mise since there is not much mise can do about -the way that crate works. ::: +::: info +This uses [dotenvy](https://crates.io/crates/dotenvy) under the hood. If you have problems with +the way `env._.file` works, you will likely need to post an issue there, +not to mise since there is not much mise can do about the way that crate works. +::: -Or set [`MISE_ENV_FILE=.env`](/configuration#mise-env-file) to automatically load dotenv files in any directory. +Or set [`MISE_ENV_FILE=.env`](/configuration#mise-env-file) to automatically load dotenv files in any +directory. You can also use json or yaml files: @@ -98,11 +104,7 @@ _.path = [ ] ``` -Adding a relative path like `tools/bin` or `./tools/bin` is similar to adding a path rooted at -`{{config_root}}`, but behaves differently if your config file is nested in a subdirectory like -`/path/to/project/.config/mise/config.toml`. Including `tools/bin` will add the path -`/path/to/project/.config/mise/tools/bin`, whereas including `{{config_root}}/tools/bin` will add the -path `/path/to/project/tools/bin`. +Adding a relative path like `tools/bin` or `./tools/bin` is similar to adding a path rooted at `{{config_root}}`, but behaves differently if your config file is nested in a subdirectory like `/path/to/project/.config/mise/config.toml`. Including `tools/bin` will add the path `/path/to/project/.config/mise/tools/bin`, whereas including `{{config_root}}/tools/bin` will add the path `/path/to/project/tools/bin`. ### `env._.source` @@ -113,24 +115,25 @@ Source an external bash script and pull exported environment variables out of it _.source = "./script.sh" ``` -::: info This **must** be a script that runs in bash as if it were executed like this: +::: info +This **must** be a script that runs in bash as if it were executed like this: ```sh source ./script.sh ``` -The shebang will be **ignored**. See [#1448](https://github.com/jdx/mise/issues/1448) for a potential alternative that -would work with binaries or other script languages. ::: +The shebang will be **ignored**. See [#1448](https://github.com/jdx/mise/issues/1448) +for a potential alternative that would work with binaries or other script languages. +::: ## Plugin-provided `env._` Directives -Plugins can provide their own `env._` directives. See [mise-env-sample](https://github.com/jdx/mise-env-sample) for an -example of one. +Plugins can provide their own `env._` directives. See [mise-env-sample](https://github.com/jdx/mise-env-sample) for an example of one. ## Multiple `env._` Directives -It may be necessary to use multiple `env._` directives, however TOML fails with this syntax because it has 2 identical -keys in a table: +It may be necessary to use multiple `env._` directives, however TOML fails with this syntax +because it has 2 identical keys in a table: ```toml [env] diff --git a/docs/environments/secrets.md b/docs/environments/secrets.md index 67b3071325..ddace64589 100644 --- a/docs/environments/secrets.md +++ b/docs/environments/secrets.md @@ -1,8 +1,8 @@ # Secrets -Because env vars in mise.toml can store sensitive information, mise has built-in support for reading encrypted secrets -from files. Currently, this is done with a [sops](https://getsops.io) implementation however other secret backends could -be added in the future. +Because env vars in mise.toml can store sensitive information, mise has built-in support for reading +encrypted secrets from files. Currently, this is done with a [sops](https://getsops.io) implementation +however other secret backends could be added in the future. Secrets are `.env.(json|yaml|toml)` files with a simple structure, for example: @@ -24,19 +24,21 @@ mise will automatically use a secret backend like sops if the file is encrypted. ## sops -mise uses the rust [rops](https://github.com/gibbz00/rops) library to interact with [sops](https://getsops.io) files. If -you encrypt a sops file, mise will automatically decrypt it when reading the file. sops files can be in json, yaml, or -toml format—however if you want to use toml you'll need to use the rops cli instead of sops. Otherwise, either sops or -rops will work fine. +mise uses the rust [rops](https://github.com/gibbz00/rops) library to interact with [sops](https://getsops.io) files. +If you encrypt a sops file, mise will automatically decrypt it when reading the file. sops files can +be in json, yaml, or toml format—however if you want to use toml you'll need to use the rops cli instead +of sops. Otherwise, either sops or rops will work fine. -::: info Currently age is the only sops encryption method supported. ::: +::: info +Currently age is the only sops encryption method supported. +::: -In order to encrypt a file with sops, you'll first need to install it (`mise use -g sops`). You'll also need to install -[age](https://github.com/FiloSottile/age) (`mise use -g age`) to generate a keypair for sops to use if you have not -already done so. +In order to encrypt a file with sops, you'll first need to install it (`mise use -g sops`). You'll +also need to install [age](https://github.com/FiloSottile/age) (`mise use -g age`) to generate a keypair for sops to use +if you have not already done so. -To generate a keypair with age run the following and note the public key that is output to use in the next command to -`sops`: +To generate a keypair with age run the following and note the public key that is output to use +in the next command to `sops`: ```sh $ age-keygen -o ~/.config/mise/age.txt @@ -49,11 +51,13 @@ Assuming we have a `.env.json` file like at the top of this doc, we can now encr sops encrypt -i --age "" .env.json ``` -::: tip The `-i` here overwrites the file with an encrypted version. This encrypted version is safe to commit into your -repo as without the private key (`~/.config/mise/age.txt` in this case) the file is useless. +::: tip +The `-i` here overwrites the file with an encrypted version. This encrypted version is safe to commit +into your repo as without the private key (`~/.config/mise/age.txt` in this case) the file is useless. You can later decrypt the file with `sops decrypt -i .env.json` or edit it in EDITOR with `sops edit .env.json`. -However, you'll first need to set SOPS_AGE_KEY_FILE to `~/.config/mise/age.txt` to decrypt the file. ::: +However, you'll first need to set SOPS_AGE_KEY_FILE to `~/.config/mise/age.txt` to decrypt the file. +::: Lastly, we need to add the file to our mise config which can be done with `mise set _.file=.env.json`. diff --git a/docs/external-resources.md b/docs/external-resources.md index 7a94419f46..b30a9d9091 100644 --- a/docs/external-resources.md +++ b/docs/external-resources.md @@ -3,12 +3,9 @@ Links to articles, videos, and other resources that are relevant to mise. - 2024-11-20 - Migrating from nvm to mise - -- 2024-06-27 - Managing Development Tool Versions with mise - - -- 2024-06-09 - Replacing pyenv, nvm, direnv with Mise - - +- 2024-06-27 - Managing Development Tool Versions with mise - +- 2024-06-09 - Replacing pyenv, nvm, direnv with Mise - - 2024-04-07 - Lalaluka stream: Grroxy, Cook, and jdx/mise - -- 2024-01-14 - Manage all your runtime versions with one tool (asdf, mise) - - +- 2024-01-14 - Manage all your runtime versions with one tool (asdf, mise) - - 2023-12-30 - You should be using mise - - 2023-03-04 - Beginner's Guide to rtx (mise) - diff --git a/docs/faq.md b/docs/faq.md index 1c69f6393d..b5e6cc6a7b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -2,98 +2,114 @@ ## I don't want to put a `mise.toml`/`.tool-versions` file into my project since git shows it as an untracked file -Use [`mise.local.toml`](https://mise.jdx.dev/configuration.html#mise-toml) and put that into your global gitignore file. -This file should never be committed. +Use [`mise.local.toml`](https://mise.jdx.dev/configuration.html#mise-toml) and put that into your global gitignore file. This file should never be committed. If you really want to use a `mise.toml` or `.tool-versions`, here are 3 ways to make git ignore these files: -- Adding `mise.toml` to project's `.git/info/exclude`. This file is local to your project so there is no need to commit - it. -- Adding `mise.toml` to project's `.gitignore` file. This has the downside that you need to commit the change to the - ignore file. -- Adding `mise.toml` to global gitignore (`core.excludesFile`). This will cause git to ignore `mise.toml` files in all - projects. You can explicitly add one to a project if needed with `git add --force mise.toml`. +- Adding `mise.toml` to project's `.git/info/exclude`. This file is local to your project so + there is no need to commit it. +- Adding `mise.toml` to project's `.gitignore` file. This has the downside that you need to + commit the change to the ignore file. +- Adding `mise.toml` to global gitignore (`core.excludesFile`). This will cause git to + ignore `mise.toml` files in all projects. You can explicitly add one to a project if needed + with `git add --force mise.toml`. ## What is the difference between "nodejs" and "node" (or "golang" and "go")? -These are aliased. For example, `mise use nodejs@14.0` is the same as `mise install node@14.0`. This means it is not -possible to have these be different plugins. +These are aliased. For example, `mise use nodejs@14.0` is the same as `mise install node@14.0`. This +means it is not possible to have these be different plugins. -This is for convenience so you don't need to remember which one is the "official" name. However if something with the -aliasing is acting up, submit a ticket or just stick to using "node" and "go". Under the hood, when mise reads a config -file or takes CLI input it will swap out "nodejs" and "golang". +This is for convenience so you don't need to remember which one is the "official" name. However if +something with the aliasing is acting up, submit a ticket or just stick to using "node" and "go". +Under the hood, when mise reads a config file or takes CLI input it will swap out "nodejs" and +"golang". -While this change is rolling out, there is some migration code that will move installs/plugins from the "nodejs" and -"golang" directories to the new names. If this runs for you you'll see a message but it should not run again unless -there is some kind of problem. In this case, it's probably easiest to just run +While this change is rolling out, there is some migration code that will move installs/plugins from +the "nodejs" and "golang" directories to the new names. If this runs for you you'll see a message +but it should not run again unless there is some kind of problem. In this case, it's probably +easiest to just +run `rm -rf ~/.local/share/mise/installs/{golang,nodejs} ~/.local/share/mise/plugins/{golang,nodejs}`. Once most users have migrated over this migration code will be removed. ## What does `mise activate` do? -It registers a shell hook to run `mise hook-env` every time the shell prompt is displayed. `mise hook-env` checks the -current env vars (most importantly `PATH` but there are others like `GOROOT` or `JAVA_HOME` for some tools) and -adds/removes/updates the ones that have changed. +It registers a shell hook to run `mise hook-env` every time the shell prompt is displayed. +`mise hook-env` checks the current env vars (most importantly `PATH` but there are others like +`GOROOT` or `JAVA_HOME` for some tools) and adds/removes/updates the ones that have changed. -For example, if you `cd` into a different directory that has `java 18` instead of `java 17` specified, just before the -next prompt is displayed the shell runs: `eval "$(mise hook-env)"` which will execute something like this in the current -shell session: +For example, if you `cd` into a different directory that has `java 18` instead of `java 17` +specified, just before the next prompt is displayed the shell runs: `eval "$(mise hook-env)"` +which will execute something like this in the current shell session: ```sh export JAVA_HOME=$HOME/.local/share/installs/java/18 export PATH=$HOME/.local/share/installs/java/18/bin:$PATH ``` -In reality updating `PATH` is a bit more complex than that because it also needs to remove java-17, but you get the -idea. - -You may think that is excessive to run `mise hook-env` every time the prompt is displayed and it should only run on -`cd`, however there are plenty of situations where it needs to run without the directory changing, for example if -`.tool-versions` or `mise.toml` was just edited in the current shell. - -Because it runs on prompt display, if you attempt to use `mise activate` in a non-interactive session (like a bash -script), it will never call `mise hook-env` and in effect will never modify PATH because it never displays a prompt. For -this type of setup, you can either call `mise hook-env` manually every time you wish to update PATH, or use -[shims](/dev-tools/shims.md) instead (preferred). Or if you only need to use mise for certain commands, just prefix the -commands with [`mise x --`](./cli/exec). For example, `mise x -- npm test` or `mise x -- ./my_script.sh`. - -`mise hook-env` will exit early in different situations if no changes have been made. This prevents adding latency to -your shell prompt every time you run a command. You can run `mise hook-env` yourself to see what it outputs, however it -is likely nothing if you're in a shell that has already been activated. - -`mise activate` also creates a shell function (in most shells) called `mise`. This is a trick that makes it possible for -`mise shell` and `mise deactivate` to work without wrapping them in `eval "$(mise shell)"`. +In reality updating `PATH` is a bit more complex than that because it also needs to remove java-17, +but you get the idea. + +You may think that is excessive to run `mise hook-env` every time the prompt is displayed +and it should only run on `cd`, however there are plenty of +situations where it needs to run without the directory changing, for example if `.tool-versions` or +`mise.toml` was just edited in the current shell. + +Because it runs on prompt display, if you attempt to use `mise activate` in a +non-interactive session (like a bash script), it will never call `mise hook-env` and in effect will +never modify PATH because it never displays a prompt. For this type of setup, you can either call +`mise hook-env` manually every time you wish to update PATH, or use [shims](/dev-tools/shims.md) +instead (preferred). +Or if you only need to use mise for certain commands, just prefix the commands with +[`mise x --`](./cli/exec). +For example, `mise x -- npm test` or `mise x -- ./my_script.sh`. + +`mise hook-env` will exit early in different situations if no changes have been made. This prevents +adding latency to your shell prompt every time you run a command. You can run `mise hook-env` +yourself +to see what it outputs, however it is likely nothing if you're in a shell that has already been +activated. + +`mise activate` also creates a shell function (in most shells) called `mise`. +This is a trick that makes it possible for `mise shell` +and `mise deactivate` to work without wrapping them in `eval "$(mise shell)"`. ## Windows support? -While mise runs great in WSL, native Windows is also supported, though via the use of shims until someone adds -[powershell](https://github.com/jdx/mise/issues/3451) support. +While mise runs great in WSL, native Windows is also supported, though via the use of shims until +someone adds [powershell](https://github.com/jdx/mise/issues/3451) support. As you'll need to use shims, this means you won't have environment variables from mise.toml unless you run mise via -[`mise x`](/cli/exec) or [`mise run`](/cli/run)—though that's actually how I use mise on my mac so for me that's my -preferred workflow anyway. +[`mise x`](/cli/exec) or [`mise run`](/cli/run)—though that's actually how I use mise on my mac so +for me that's my preferred workflow anyway. ## How do I use mise with http proxies? -Short answer: just set `http_proxy` and `https_proxy` environment variables. These should be lowercase. +Short answer: just set `http_proxy` and `https_proxy` environment variables. These should be +lowercase. -This may not work with all plugins if they are not configured to use these env vars. If you're having a proxy-related -issue installing something specific you should post an issue on the plugin's repository. +This may not work with all plugins if they are not configured to use these env vars. +If you're having a proxy-related issue installing something specific you should post an issue on the +plugin's repository. ## How do the shorthand plugin names map to repositories? e.g.: how does `mise plugin install elixir` know to fetch ? -We maintain [an index](https://github.com/mise-plugins/registry) of shorthands that mise uses as a base. This is -regularly updated every time that mise has a release. This repository is stored directly into the codebase -[here](https://github.com/jdx/mise/blob/main/registry.toml). +We maintain [an index](https://github.com/mise-plugins/registry) of shorthands that mise uses as a +base. +This is regularly updated every time that mise has a release. This repository is stored directly +into +the codebase [here](https://github.com/jdx/mise/blob/main/registry.toml). ## Does "node@20" mean the newest available version of node? -It depends on the command. Normally, for most commands and inside of config files, "node@20" will point to the latest -_installed_ version of node-20.x. You can find this version by running `mise latest --installed node@20` or by seeing -what the `~/.local/share/mise/installs/node/20` symlink points to: +It depends on the command. Normally, for most commands and inside of config files, "node@20" will +point to the latest _installed_ version of node-20.x. You can find this version by running +`mise latest --installed node@20` or by seeing what the `~/.local/share/mise/installs/node/20` +symlink +points to: ```sh $ ls -l ~/.local/share/mise/installs/node/20 @@ -106,8 +122,8 @@ There are some exceptions to this, such as the following: - `mise latest node@20` - `mise upgrade node@20` -These will use the latest _available_ version of node-20.x. This generally makes sense because you wouldn't want to -install a version that is already installed. +These will use the latest _available_ version of node-20.x. This generally makes sense because you +wouldn't want to install a version that is already installed. ## How do I migrate from asdf? @@ -125,37 +141,36 @@ mv ~/.tool-versions ~/.tool-versions.bak cat ~/.tool-versions.bak | tr ' ' '@' | xargs -n2 mise use -g ``` -Once you are comfortable with mise, you can remove the `.tool-versions.bak` file and -[uninstall `asdf`](https://asdf-vm.com/manage/core.html#uninstall) +Once you are comfortable with mise, you can remove the `.tool-versions.bak` file and [uninstall `asdf`](https://asdf-vm.com/manage/core.html#uninstall) ## How compatible is mise with asdf? -mise should be able to read/install any `.tool-versions` file used by asdf. Any asdf plugin should be usable in mise. -The commands in mise are slightly different, such as `mise install node@20.0.0` vs `asdf install node 20.0.0`—this is -done so multiple tools can be specified at once. However, asdf-style syntax is still supported: -(`mise install node 20.0.0`). This is the case for most commands, though the help for the command may say that -asdf-style syntax is supported. When in doubt, just try asdf syntax and see if it works—it probably does. +mise should be able to read/install any `.tool-versions` file used by asdf. Any asdf plugin +should be usable in mise. The commands in mise are slightly +different, such as `mise install node@20.0.0` vs `asdf install node 20.0.0`—this is done so +multiple tools can be specified at once. However, asdf-style syntax is still supported: (`mise +install node 20.0.0`). This is the case for most commands, though the help for the command may +say that asdf-style syntax is supported. When in doubt, just try asdf syntax and see if it works—it probably does. -UPDATE (2025-01-01): mise was designed to be compatible with the asdf written in bash (<=0.15). The new asdf written in -go (>=0.16) has commands mise does not support like `asdf set`. `mise set` is an existing command that is completely -different than `asdf set`—in mise that sets env vars. +UPDATE (2025-01-01): mise was designed to be compatible with the asdf written in bash (<=0.15). The new asdf written in go (>=0.16) +has commands mise does not support like `asdf set`. `mise set` is an existing command that is completely different than `asdf set`—in mise that sets env vars. -This isn't important for usability reasons so much as making it so plugins continue to work that call asdf commands -inside of the plugin code. +This isn't important for usability reasons so much as making it so plugins continue to work that +call asdf commands inside of the plugin code. -Using commands like `mise use` may output `.tool-versions` files that are not compatible with asdf, such as using fuzzy -versions. You can set `--pin` or `MISE_PIN=1` to make `mise use` output asdf-compatible versions in `.tool-versions`. -Alternatively, you can have `mise.toml` and `.tool-versions` sitting side-by-side. `mise.toml` tools will override tools -defined in a `.tool-versions` in the same directory. +Using commands like `mise use` may output `.tool-versions` files that are not compatible with asdf, +such as using fuzzy versions. You can set `--pin` or `MISE_PIN=1` to make `mise use` output asdf-compatible versions +in `.tool-versions`. Alternatively, you can have `mise.toml` and `.tool-versions` sitting side-by-side. `mise.toml` tools +will override tools defined in a `.tool-versions` in the same directory. -That said, in general compatibility with asdf is no longer a design goal. It's long been the case that there is no -reason to prefer asdf to mise so users should migrate. While plenty of users have teams which use both in tandem, issues -with such a setup are unlikely to be prioritized. +That said, in general compatibility with asdf is no longer a design goal. It's long been the case +that there is no reason to prefer asdf to mise so users should migrate. While plenty of users have +teams which use both in tandem, issues with such a setup are unlikely to be prioritized. ## How do I disable/force CLI color output? -mise uses [console.rs](https://docs.rs/console/latest/console/fn.colors_enabled.html) which honors the -[clicolors spec](https://bixense.com/clicolors/): +mise uses [console.rs](https://docs.rs/console/latest/console/fn.colors_enabled.html) which +honors the [clicolors spec](https://bixense.com/clicolors/): - `CLICOLOR != 0`: ANSI colors are supported and should be used when the program isn’t piped. - `CLICOLOR == 0`: Don’t output ANSI color escape codes. @@ -163,9 +178,10 @@ mise uses [console.rs](https://docs.rs/console/latest/console/fn.colors_enabled. ## Is mise secure? -Providing a secure supply chain is incredibly important. mise already provides a more secure experience when compared to -asdf. Security-oriented evaluations and contributions are welcome. We also urge users to look after the plugins they -use, and urge plugin authors to look after the users they serve. +Providing a secure supply chain is incredibly important. mise already provides a more secure +experience when compared to asdf. Security-oriented evaluations and contributions are welcome. +We also urge users to look after the plugins they use, and urge plugin authors to look after +the users they serve. For more details see [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md). @@ -173,11 +189,8 @@ For more details see [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURIT usage () is a spec and CLI for defining CLI tools. -Arguments, flags, environment variables, and config files can all be defined in a Usage spec. It can be thought of like -OpenAPI (swagger) for CLIs. +Arguments, flags, environment variables, and config files can all be defined in a Usage spec. It can be thought of like OpenAPI (swagger) for CLIs. -`usage` can be installed with `mise` using `mise use -g usage` and is required to get the autocompetion working. See -[autocompletion](/installing-mise.html#autocompletion). +`usage` can be installed with `mise` using `mise use -g usage` and is required to get the autocompetion working. See [autocompletion](/installing-mise.html#autocompletion). -You can leverage usage in file tasks to get auto-completion working, see -[file tasks arguments](/tasks/file-tasks.html#arguments). +You can leverage usage in file tasks to get auto-completion working, see [file tasks arguments](/tasks/file-tasks.html#arguments). diff --git a/docs/getting-started.md b/docs/getting-started.md index 001e3f437a..facc568038 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,13 +1,13 @@ # Getting Started -This will show you how to install mise and get started with it. This is a suitable way when using an interactive shell -like `bash`, `zsh`, or `fish`. +This will show you how to install mise and get started with it. This is a suitable way when using an interactive shell like `bash`, `zsh`, or `fish`. ## 1. Install `mise` CLI See [installing mise](/installing-mise) for other ways to install mise (`macport`, `apt`, `yum`, `nix`, etc.). -:::tabs key:installing-mise == Linux/macOS +:::tabs key:installing-mise +== Linux/macOS ```shell curl https://mise.run | sh @@ -21,15 +21,18 @@ You can verify the installation by running: # mise 2024.x.x ``` -- `~/.local/bin` does not need to be in `PATH`. mise will automatically add its own directory to `PATH` when activated. +- `~/.local/bin` does not need to be in `PATH`. mise will automatically add its own directory to `PATH` + when activated. -== Brew Using [brew](https://brew.sh/) package manager +== Brew +Using [brew](https://brew.sh/) package manager ```shell brew install mise ``` -== Windows ::: code-group +== Windows +::: code-group ```shell [winget] winget install jdx.mise @@ -66,24 +69,23 @@ sudo apt install -y mise ::: -`mise` respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like to change these -locations. +`mise` respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like +to change these locations. ## 2. Activate `mise` Now that `mise` is installed, you can optionally activate it or add its [shims](dev-tools/shims.md) to `PATH`. -- [`mise activate`](/cli/activate) method updates your environment variable and `PATH` every time your prompt is run to - ensure you use the correct versions. -- [Shims](dev-tools/shims.md) are symlinks to the `mise` binary that intercept commands and load the appropriate - environment +- [`mise activate`](/cli/activate) method updates your environment variable and `PATH` every time your prompt is run to ensure you use the correct versions. +- [Shims](dev-tools/shims.md) are symlinks to the `mise` binary that intercept commands and load the appropriate environment -::: warning Shims do not support all the features of `mise activate`.
See -[shims vs path](/dev-tools/shims.html#shims-vs-path) for more info. ::: +::: warning +Shims do not support all the features of `mise activate`.
+See [shims vs path](/dev-tools/shims.html#shims-vs-path) for more info. +::: -For interactive shells, `mise activate` is recommended. In non-interactive sessions, like CI/CD, IDEs, and scripts, -using `shims` might work best. You can also not use any and call `mise exec/run` directly instead. See -[this guide](dev-tools/shims.md) for more information. +For interactive shells, `mise activate` is recommended. In non-interactive sessions, like CI/CD, IDEs, and scripts, using `shims` might work best. You can also not use any and call `mise exec/run` directly instead. +See [this guide](dev-tools/shims.md) for more information. :::tabs key:installing-mise @@ -103,9 +105,12 @@ echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish ``` -- Make sure you restart your shell session after modifying your rc file in order for it to take effect. -- Also note that this uses `~/.local/bin/mise` as the binary location since that's what uses by - default. If you've installed mise by some other means it may be on `PATH` or somewhere different. +- Make sure you restart your shell session after modifying your rc file in order for it to take + effect. +- Also note that + this uses `~/.local/bin/mise` as the binary location since that's what uses by + default. If you've + installed mise by some other means it may be on `PATH` or somewhere different. == Brew @@ -119,8 +124,7 @@ echo 'eval "$(/opt/homebrew/bin/mise activate bash)"' >> ~/.bashrc echo 'eval "$(/opt/homebrew/bin/mise activate zsh)"' >> ~/.zshrc ``` -- Activation will be handled automatically if you use `fish` shell and installed via `homebrew`. This can be disabled - with `set -Ux MISE_FISH_AUTO_ACTIVATE 0`. +- Activation will be handled automatically if you use `fish` shell and installed via `homebrew`. This can be disabled with `set -Ux MISE_FISH_AUTO_ACTIVATE 0`. - Make sure you restart your shell session after modifying your rc file in order for it to take effect. == Windows @@ -157,8 +161,11 @@ echo 'mise activate fish | source' >> ~/.config/fish/config.fish ## 3. Using `mise` -:::info Of course, if using mise solely for [environment management](/environments/) or [running tasks](/tasks/) this -step is not necessary. You can use it to make sure `mise` is correctly setup. ::: +:::info +Of course, if using mise solely for [environment management](/environments/) +or [running tasks](/tasks/) +this step is not necessary. You can use it to make sure `mise` is correctly setup. +::: As an example, here is how you can install `node` and set it as the global default: @@ -173,8 +180,10 @@ mise exec -- node -v # v22.x.x ``` -:::tip Use `mise x -- node -v` or set a shell alias in your shell's rc file like `alias x="mise x --"` to save some -keystrokes. ::: +:::tip +Use `mise x -- node -v` or set a shell alias in your shell's rc file like `alias x="mise x --"` to +save some keystrokes. +::: If you did activate `mise` or add its shims to `PATH`, then `node` is also available directly! diff --git a/docs/hooks.md b/docs/hooks.md index 3b6ea1ce8b..f87307550b 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -1,8 +1,8 @@ # Hooks -You can have mise automatically execute scripts during a `mise activate` session. You cannot use these without the -`mise activate` shell hook installed in your shell—except the `preinstall` and `postinstall` hooks. The configuration -goes into `mise.toml`. +You can have mise automatically execute scripts during a `mise activate` session. You cannot use these +without the `mise activate` shell hook installed in your shell—except the `preinstall` and `postinstall` hooks. +The configuration goes into `mise.toml`. ## CD hook @@ -15,8 +15,7 @@ cd = "echo 'I changed directories'" ## Enter hook -This hook is run when the project is entered. Changing directories while in the project will not trigger this hook -again. +This hook is run when the project is entered. Changing directories while in the project will not trigger this hook again. ```toml [hooks] @@ -54,8 +53,7 @@ script = "cargo fmt" This hook will have the following environment variables set: -- `MISE_WATCH_FILES_MODIFIED`: A colon-separated list of the files that have been modified. Colons are escaped with a - backslash. +- `MISE_WATCH_FILES_MODIFIED`: A colon-separated list of the files that have been modified. Colons are escaped with a backslash. ## Hook execution @@ -63,8 +61,7 @@ Hooks are executed with the following environment variables set: - `MISE_ORIGINAL_CWD`: The directory that the user is in. - `MISE_PROJECT_DIR`: The root directory of the project. -- `MISE_PREVIOUS_DIR`: The directory that the user was in before the directory change (only if a directory change - occurred). +- `MISE_PREVIOUS_DIR`: The directory that the user was in before the directory change (only if a directory change occurred). ## Shell hooks @@ -76,10 +73,12 @@ shell = "bash" script = "source completions.sh" ``` -::: warning I feel this should be obvious but in case it's not, this isn't going to do any sort of cleanup when you -_leave_ the directory like using `[env]` does in `mise.toml`. You're literally just executing shell code when you enter -the directory which mise has no way to track at all. I don't think there is a solution to this problem and it's likely -the reason direnv has never implemented something similar. +::: warning +I feel this should be obvious but in case it's not, this isn't going to do any sort of cleanup +when you _leave_ the directory like using `[env]` does in `mise.toml`. You're literally just +executing shell code when you enter the directory which mise has no way to track at all. +I don't think there is a solution to this problem and it's likely the reason direnv has never +implemented something similar. I think in most situations this is probably fine, though worth keeping in mind. diff --git a/docs/how-i-use-mise.md b/docs/how-i-use-mise.md index b3c7ca3df4..d30a0da9a8 100644 --- a/docs/how-i-use-mise.md +++ b/docs/how-i-use-mise.md @@ -1,33 +1,41 @@ # How I use mise -This is a very different doc than the rest of the site. It's not my intention to make this valuable to anyone. In fact -it may end up being useful to 0 people. +This is a very different doc than the rest of the site. It's not my +intention to make this valuable to anyone. In fact it may end up being +useful to 0 people. -I'm probably the strangest user of mise out there. My use case is the most atypical for a number of reasons I'll get to. -That said, I often find myself saying to friends "you know the way I use mise..." and thought it might be useful to -actually write down the way I use it in case anyone is interested. +I'm probably the strangest user of mise out there. My use case is the +most atypical for a number of reasons I'll get to. That said, I often +find myself saying to friends "you know the way I use mise..." and thought +it might be useful to actually write down the way I use it in case +anyone is interested. -This is an advanced article. I'm not going to take the time to explain the tools and techniques here. If you're curious, -file an issue or ask me in the Discord. +This is an advanced article. I'm not going to take the time to explain +the tools and techniques here. If you're curious, file an issue or ask +me in the Discord. ## My setup -I use a mac with fish shell and am a heavy homebrew user. I've been using both for over a decade. +I use a mac with fish shell and am a heavy homebrew user. I've been using +both for over a decade. -My main editor(s) are JetBrains products (IntelliJ, RustRover, Webstorm). I also use nvim as a secondary editor -(Astronvim with some minimal config). I probably spend 70% of my time in JetBrains. +My main editor(s) are JetBrains products (IntelliJ, RustRover, Webstorm). +I also use nvim as a secondary editor (Astronvim with some minimal config). +I probably spend 70% of my time in JetBrains. -I tend to keep a terminal open (kitty) while working in JetBrains. I do not often run tests or builds with in the IDE. -Not sure why, just never been in the habit of that. (Because of that these docs and possibly mise support in IDEs may -not be what it should be-it's just not how I work personally). +I tend to keep a terminal open (kitty) while working in JetBrains. I do not +often run tests or builds with in the IDE. Not sure why, just never been +in the habit of that. (Because of that these docs and possibly mise support in +IDEs may not be what it should be-it's just not how I work personally). ## `mise activate` -Unlike most mise users, I don't use `mise activate` or shims at all unless I'm explicitly testing them-and that's rarely -the case. It certainly doesn't go into my `~/.config/fish/config.fish`. +Unlike most mise users, I don't use `mise activate` or +shims at all unless I'm explicitly testing them-and that's rarely the +case. It certainly doesn't go into my `~/.config/fish/config.fish`. -Because I work on mise itself, I often need to rebuild it and run the code from my repo. For this, I have the following -bash shim located in `~/bin/@mise`: +Because I work on mise itself, I often need to rebuild it and run the code from my repo. For this, I have the following bash shim located in +`~/bin/@mise`: ```fish #!/usr/bin/env bash @@ -36,10 +44,12 @@ set -euo pipefail exec cargo run -q --all-features --manifest-path ~/src/mise/Cargo.toml -- "$@" ``` -:::info The "@" prefix I use for things that will perform a rebuild-i.e.: they're slow. ::: +:::info +The "@" prefix I use for things that will perform a rebuild-i.e.: they're slow. +::: -This way I can easily test mise in any directory with `@mise`. I probably run this more often than without just out of -habit. For example, if I want to test `mise activate` in zsh: +This way I can easily test mise in any directory with `@mise`. I probably +run this more often than without just out of habit. For example, if I want to test `mise activate` in zsh: ```sh zsh @@ -48,38 +58,52 @@ eval "$(@mise activate zsh)" ## Minimal tools -Might be surprising to folks but I don't use too many mise plugins. Well I have a lot in my config, but I don't actually -use them. They're for testing. +Might be surprising to folks but I don't use too many mise plugins. Well +I have a lot in my config, but I don't actually use them. They're for +testing. -I tend to basically just use core plugins. I like mise for managing things where I really care about the major version -(like node). If it's something like `shfmt` or `jq` I don't really care about the version. I just want the latest and -for me, I find `brew` to be better suited to that purpose. +I tend to basically just use core plugins. I like mise for managing +things where I really care about the major version (like node). If it's +something like `shfmt` or `jq` I don't really care about the version. +I just want the latest and for me, I find `brew` to be better suited to +that purpose. -I recognize that some people really like locking down their versions across a team to keep things consistent. I think -that's great too. Part of this is that I'm currently at Amazon where the tooling story is complicated let's just say-not -in a bad way, just one where integrating mise into the setup isn't as straightforward as a smaller company would be. +I recognize that some people really like locking down their versions +across a team to keep things consistent. I think that's great too. +Part of this is that I'm currently at Amazon where the tooling story +is complicated let's just say-not in a bad way, just one where +integrating mise into the setup isn't as straightforward as a smaller +company would be. -Outside of Amazon I have a handful of open source projects, mostly mise-related and mostly fairly simple. Also mostly -rust where I don't use mise anyways. +Outside of Amazon I have a handful of open source projects, mostly +mise-related and mostly fairly simple. Also mostly rust where I don't +use mise anyways. -The one big exception here is node which I quite like mise for. I assume others do to because it's by far the most -popular language. You'd probably guess that since it's my example in nearly all of the docs. +The one big exception here is node which I quite like mise for. I assume +others do to because it's by far the most popular language. You'd +probably guess that since it's my example in nearly all of the docs. -That said, part of the reason for doing that in the docs is that it's 4 characters and everyone knows what it is. +That said, part of the reason for doing that in the docs is that it's 4 +characters and everyone knows what it is. ## `.mise.local.toml` -I'm a heavy user of this concept. I rarely like to actually commit `mise.toml` files into projects. I tend to see my -mise config as my personal config that I use within other projects that I don't particularly want to share with others. +I'm a heavy user of this concept. I rarely like to actually commit `mise.toml` +files into projects. I tend to see my mise config as my personal config that +I use within other projects that I don't particularly want to share with others. -Of course, this goes into my global gitconfig so I can easily add this to shared projects without submitting a PR. +Of course, this goes into my global gitconfig so I can easily add this to +shared projects without submitting a PR. -One day when tasks is out of experimental, I may do this a lot less since I think tasks are one thing I really want to -share. For me, the `[tools]` section is just so easy to write I don't mind doing it and don't like imposing the way that -**I** setup my machine on others. +One day when tasks is out of experimental, I may do this a lot less since I +think tasks are one thing I really want to share. For me, the `[tools]` +section is just so easy to write I don't mind doing it and don't like +imposing the way that **I** setup my machine on others. -There is a social aspect of this as well that I'm conscious of. I'm the author of `mise`. To me it's a little -self-serving to go into a project and add a config for my own project. I'd love if _someone else_ did that instead. +There is a social aspect of this as well that I'm conscious of. I'm +the author of `mise`. To me it's a little self-serving to go into a project +and add a config for my own project. I'd love if _someone else_ did that +instead. ## `~/.mise` @@ -92,5 +116,7 @@ ln -s ~/.mise ~/.local/state/mise ln -s ~/.mise/cache ~/.cache/mise ``` -It is good that mise generally follows XDG spec, but for tools that I interact with a lot I like to put them at the top -level like this. Obviously, mise doesn't mind if all of these point to the same place or else it would not work for me. +It is good that mise generally follows XDG spec, but for tools that I interact +with a lot I like to put them at the top level like this. Obviously, +mise doesn't mind if all of these point to the same place or else it would +not work for me. diff --git a/docs/ide-integration.md b/docs/ide-integration.md index 52089ee9e5..9dcde7e9fc 100644 --- a/docs/ide-integration.md +++ b/docs/ide-integration.md @@ -2,36 +2,24 @@ Code editors and IDEs work differently than interactive shells. -Usually, they will either inherit the environment from your current shell (this is the case if you start it from a -terminal like `nvim .` or `code .`) or will have -[their own way](https://github.com/microsoft/vscode-docs/blob/906acccd6180d8425577f8297ed29e221ad3daca/docs/supporting/faq.md?plain=1#L238) -to set up the environment. +Usually, they will either inherit the environment from your current shell (this is the case if you start it from a terminal like `nvim .` or `code .`) or will have [their own way](https://github.com/microsoft/vscode-docs/blob/906acccd6180d8425577f8297ed29e221ad3daca/docs/supporting/faq.md?plain=1#L238) to set up the environment. -Once you have launched the IDE, it won't reload the environment variables or the `PATH` provided by `mise` if you update -your mise configuration files. Therefore, we cannot rely on the default `mise activate` method to automatically set up -the editor. +Once you have launched the IDE, it won't reload the environment variables or the `PATH` provided by `mise` if you update your mise configuration files. Therefore, we cannot rely on the default `mise activate` method to automatically set up the editor. There are a few ways to make `mise` work with your editor: -- Some editors or IDE plugins have direct support for `mise` and can let you select the tools/sdk path from the IDE - settings. This will let you access to the tool binaries but won't load the environment variables. -- Most editors (and language plugins) will look for tools on the `PATH` and run them in the context of your project. - Therefore, adding the `mise` shims to the `PATH` might be enough (see [below](#adding-shims-to-path-default-shell)). - This will run the tool provided by mise and load the environment variables. -- In other cases, you may need to manually indicate the path to the tools provided by `mise` in the IDE settings. This - can be done by using [`mise which `](./cli/which.md) or [`mise where`](./cli/where). You can also provide the - path to the tool shim (e.g. `~/.local/share/mise/shims/node`) if the plugin supports it as this will also load the - environment variables when the tool is run. -- Finally, some custom plugins have been developed to work with `mise`. You can find them in the - [IDE Plugins](#ide-plugins) section. +- Some editors or IDE plugins have direct support for `mise` and can let you select the tools/sdk path from the IDE settings. This will let you access to the tool binaries but won't load the environment variables. +- Most editors (and language plugins) will look for tools on the `PATH` and run them in the context of your project. Therefore, adding the `mise` shims to the `PATH` might be enough (see [below](#adding-shims-to-path-default-shell)). This will run the tool provided by mise and load the environment variables. +- In other cases, you may need to manually indicate the path to the tools provided by `mise` in the IDE settings. This can be done by using [`mise which `](./cli/which.md) or [`mise where`](./cli/where). You can also provide the path to the tool shim (e.g. `~/.local/share/mise/shims/node`) if the plugin supports it as this will also load the environment variables when the tool is run. +- Finally, some custom plugins have been developed to work with `mise`. You can find them in the [IDE Plugins](#ide-plugins) section. ## Adding shims to PATH in your default shell profile {#adding-shims-to-path-default-shell} -IDEs work better with [shims](./dev-tools/shims) than they do environment variable modifications. The simplest way is to -add the mise shim directory to `PATH`. +IDEs work better with [shims](./dev-tools/shims) than they do environment variable modifications. The simplest way is +to add the mise shim directory to `PATH`. -For IntelliJ and VSCode—and likely others, you can modify your default shell's profile script. Your default shell can be -found with: +For IntelliJ and VSCode—and likely others, you can modify your default shell's profile +script. Your default shell can be found with: ::: code-group @@ -45,8 +33,8 @@ getent passwd $USER | cut -d: -f7 ::: -You can change your default shell with `chsh -s /path/to/shell` but you may need to first add it to `/etc/shells`. Once -you know the right one, modify the appropriate file: +You can change your default shell with `chsh -s /path/to/shell` but you may need +to first add it to `/etc/shells`. Once you know the right one, modify the appropriate file: ::: code-group @@ -71,20 +59,22 @@ end ::: -This assumes that `mise` is on `PATH`. If it is not, you'll need to use the absolute path ( e.g.: -`eval "$($HOME/.local/bin/mise activate zsh --shims)"`). +This assumes that `mise` is on `PATH`. If it is not, you'll need to use the absolute path ( +e.g.: `eval "$($HOME/.local/bin/mise activate zsh --shims)"`). Here is an example showing that VSCode will use `node` provided by `mise`: -::: tabs === VSCode +::: tabs +=== VSCode [![vscode using shims](./shims-vscode.png)](./shims-vscode.png) -=== IntelliJ [![intellij using shims](./shims-intellij.png)](./shims-intellij.png) ::: +=== IntelliJ +[![intellij using shims](./shims-intellij.png)](./shims-intellij.png) +::: -As mentioned above, using `shims` doesn't work with all mise features. For example, arbitrary -[env vars](./environments/) in `[env]` will only be set if a shim is executed. For this we need tighter integration with -the IDE and/or a custom plugin. +As mentioned above, using `shims` doesn't work with all mise features. For example, arbitrary [env vars](./environments/) in `[env]` will +only be set if a shim is executed. For this we need tighter integration with the IDE and/or a custom plugin. ## IDE Plugins @@ -94,9 +84,9 @@ Here are some community plugins that have been developed to work with `mise`: - IntelliJ: [intellij-mise](https://github.com/134130/intellij-mise) - VSCode: [mise-vscode](https://github.com/hverlin/mise-vscode) -If you want to build a custom plugin for your editor, have a look at the existing plugins or take a look at existing -direnv extensions and see if you can modify it to work for `mise`.`direnv` and `mise` work similarly and there should be -a direnv extension that can be used as a starting point. +If you want to build a custom plugin for your editor, have a look at the existing plugins or take a look at existing direnv extensions and see if you can modify it to +work for `mise`.`direnv` and `mise` work similarly and there should be a direnv extension that can be used as a starting +point. ## Vim @@ -127,8 +117,7 @@ vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH -> A GNU Emacs library which uses the mise tool to determine per-directory/project environment variables and then set -> those environment variables on a per-buffer basis. +> A GNU Emacs library which uses the mise tool to determine per-directory/project environment variables and then set those environment variables on a per-buffer basis. ```lisp (require 'mise) @@ -141,20 +130,19 @@ vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH -This plugin can automatically configure the IDE to use the tools provided by mise. It has also some support for running -mise tasks and loading environment variables in the run configurations. +This plugin can automatically configure the IDE to use the tools provided by mise. It has also some support for running mise tasks and loading environment variables in the run configurations. ### Direct SDK selection -Some JetBrains IDEs (or language plugins) have direct support for `mise`. This allows you to select the SDK version from -the IDE settings. Example for Java: +Some JetBrains IDEs (or language plugins) have direct support for `mise`. This allows you to select the SDK version from the IDE settings. +Example for Java: ![SDK settings](./intellij-sdk-selection.png) ### SDK selection using asdf layout -Some plugins cannot find SDK installed by `mise` yet but might have support for asdf. In that case, a workaround is to -symlink the mise tool directory which has same layout as asdf: +Some plugins cannot find SDK installed by `mise` yet but might have support for asdf. +In that case, a workaround is to symlink the mise tool directory which has same layout as asdf: ```sh ln -s ~/.local/share/mise ~/.asdf @@ -172,8 +160,7 @@ Or in the case of node (possibly other languages), it's under "Languages & Frame ### VSCode Plugin -There is a [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=hverlin.mise-vscode) which can configure -other extensions for you, without having to modify your shell profile to add the shims to `PATH`. +There is a [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=hverlin.mise-vscode) which can configure other extensions for you, without having to modify your shell profile to add the shims to `PATH`. In addition, it provides additional features such as: @@ -187,7 +174,8 @@ In addition, it provides additional features such as: ### Use [`mise exec`](./cli/exec) in launch Configuration -While modifying your default shell profile is likely the easiest solution, you can also set the tools in `launch.json`: +While modifying your default shell profile is likely the easiest solution, you can also set +the tools in `launch.json`: ::: details mise exec launch.json example @@ -216,10 +204,11 @@ While modifying your default shell profile is likely the easiest solution, you c ## Xcode -Xcode projects can run system commands from script build phases and schemes. Since Xcode sandboxes the execution of the -script using the tool `/usr/bin/sandbox-exec`, don't expect Mise and the automatically-activated tools to work out of -the box. First, you'll need to add `$(SRCROOT)/mise.toml` to the list of **Input files**. This is necessary for Xcode to -allow reads to that file. Then, you can use `mise activate` to activate the tools you need: +Xcode projects can run system commands from script build phases and schemes. Since Xcode sandboxes +the execution of the script using the tool `/usr/bin/sandbox-exec`, don't expect Mise and the +automatically-activated tools to work out of the box. First, you'll need to +add `$(SRCROOT)/mise.toml` to the list of **Input files**. This is necessary for Xcode to allow +reads to that file. Then, you can use `mise activate` to activate the tools you need: ```bash # -C ensures that Mise loads the configuration from the Mise configuration @@ -231,9 +220,13 @@ swiftlint ## [YOUR IDE HERE] -I am not a heavy IDE user. I use JetBrains products but I don't actually like to execute code directly inside of them -often so I don't have much personal advice to offer for IDEs generally. That said, people often ask about how to get -their IDE to work with mise so if you've done this for your IDE, please consider sending a PR to this page with some -instructions (however rough they are, starting somewhere is better than nothing). +I am not a heavy IDE user. I use JetBrains products but I don't actually +like to execute code directly inside of them often so I don't have much +personal advice to offer for IDEs generally. That said, people often +ask about how to get their IDE to work with mise so if you've done this +for your IDE, please consider sending a PR to this page with some +instructions (however rough they are, starting somewhere is better than +nothing). -Also if you've found a setup that you prefer to what is listed here consider adding it as a suggestion. +Also if you've found a setup that you prefer to what is listed here consider +adding it as a suggestion. diff --git a/docs/installing-mise.md b/docs/installing-mise.md index f44f540d55..acb4b4813a 100644 --- a/docs/installing-mise.md +++ b/docs/installing-mise.md @@ -8,8 +8,9 @@ This page lists various ways to install `mise` on your system. ### -Note that it isn't necessary for `mise` to be on `PATH`. If you run the activate script in your shell's rc file, mise -will automatically add itself to `PATH`. +Note that it isn't necessary for `mise` to be on `PATH`. If you run the activate script in your +shell's rc +file, mise will automatically add itself to `PATH`. ```sh curl https://mise.run | sh @@ -34,9 +35,11 @@ curl https://mise.jdx.dev/install.sh.sig | gpg --decrypt > install.sh sh ./install.sh ``` -::: tip As long as you don't change the version with `MISE_VERSION`, the install script will be pinned to whatever the -latest version was when it was downloaded with checksums inside the file. This makes downloading the file and putting it -into a project a great way to ensure that anyone installing with that script fetches the exact same mise bin. ::: +::: tip +As long as you don't change the version with `MISE_VERSION`, the install script will be pinned to whatever the latest +version was when it was downloaded with checksums inside the file. This makes downloading the file and putting it into +a project a great way to ensure that anyone installing with that script fetches the exact same mise bin. +::: or if you're allergic to `| sh`: @@ -89,8 +92,8 @@ For Alpine Linux: apk add mise ``` -_mise lives in the -[community repository](https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/community/mise/APKBUILD)._ +_mise lives in +the [community repository](https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/community/mise/APKBUILD)._ ### apt @@ -173,8 +176,8 @@ brew install mise ### npm -mise is available on npm as a precompiled binary. This isn't a Node.js package—just distributed via npm. This is useful -for JS projects that want to setup mise via `package.json` or `npx`. +mise is available on npm as a precompiled binary. This isn't a Node.js package—just distributed +via npm. This is useful for JS projects that want to setup mise via `package.json` or `npx`. ```sh npm install -g @jdxcode/mise @@ -209,7 +212,8 @@ For the Nix package manager, at release 23.05 or later: nix-env -iA mise ``` -You can also import the package directly using `mise-flake.packages.${system}.mise`. It supports all default Nix +You can also import the package directly using +`mise-flake.packages.${system}.mise`. It supports all default Nix systems. ### yum @@ -222,7 +226,8 @@ yum install -y mise ### Windows - Scoop -> [!NOTE] We're currently waiting for mise to be merged to the Scoop main bucket: +> [!NOTE] +> We're currently waiting for mise to be merged to the Scoop main bucket: > > - @@ -240,7 +245,9 @@ winget install jdx.mise ### Windows - Chocolatey -::: info chocolatey version is currently outdated. ::: +::: info +chocolatey version is currently outdated. +::: ```sh choco install mise @@ -248,10 +255,10 @@ choco install mise ### Windows - manual -Download the latest release from [GitHub](https://github.com/jdx/mise/releases) and add the binary to your PATH. +Download the latest release from [GitHub](https://github.com/jdx/mise/releases) and add the binary +to your PATH. -If your shell does not support `mise activate`, you would want to edit PATH to include the shims directory (by default: -`%LOCALAPPDATA%\mise\shims`). +If your shell does not support `mise activate`, you would want to edit PATH to include the shims directory (by default: `%LOCALAPPDATA%\mise\shims`). ## Shells @@ -273,15 +280,19 @@ echo 'eval "$(mise activate zsh)"' >> "${ZDOTDIR-$HOME}/.zshrc" echo 'mise activate fish | source' >> ~/.config/fish/config.fish ``` -::: tip For homebrew and possibly other installs mise is automatically activated so this is not necessary. +::: tip +For homebrew and possibly other installs mise is automatically activated so +this is not necessary. -See [`MISE_FISH_AUTO_ACTIVATE=1`](/configuration#mise_fish_auto_activate1) for more information. ::: +See [`MISE_FISH_AUTO_ACTIVATE=1`](/configuration#mise_fish_auto_activate1) for more information. +::: ### Powershell -::: warning See -[about_Profiles](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles) -docs to find your actual profile location. You will need to first create the parent directory if it does not exist. ::: +::: warning +See [about_Profiles](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles) docs to find your actual profile location. +You will need to first create the parent directory if it does not exist. +::: ```powershell echo '~/.local/bin/mise activate mise activate pwsh | Out-String | Invoke-Expression' >> $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1 @@ -289,8 +300,9 @@ echo '~/.local/bin/mise activate mise activate pwsh | Out-String | Invoke-Expres ### Nushell -Nu does [not support `eval`](https://www.nushell.sh/book/how_nushell_code_gets_run.html#eval-function) Install Mise by -appending `env.nu` and `config.nu`: +Nu +does [not support `eval`](https://www.nushell.sh/book/how_nushell_code_gets_run.html#eval-function) +Install Mise by appending `env.nu` and `config.nu`: ```nushell ' @@ -300,7 +312,8 @@ let mise_path = $nu.default-config-dir | path join mise.nu "\nuse ($nu.default-config-dir | path join mise.nu)" | save $nu.config-path --append ``` -If you prefer to keep your dotfiles clean you can save it to a different directory then update `$env.NU_LIB_DIRS`: +If you prefer to keep your dotfiles clean you can save it to a different directory then +update `$env.NU_LIB_DIRS`: ```nushell "\n$env.NU_LIB_DIRS ++= ($mise_path | path dirname | to nuon)" | save $nu.env-path --append @@ -308,9 +321,9 @@ If you prefer to keep your dotfiles clean you can save it to a different directo ### Xonsh -Since `.xsh` files are [not compiled](https://github.com/xonsh/xonsh/issues/3953) you may shave a bit off startup time -by using a pure Python import: add the code below to, for example, `~/.config/xonsh/mise.py` config file and -`import mise` it in `~/.config/xonsh/rc.xsh`: +Since `.xsh` files are [not compiled](https://github.com/xonsh/xonsh/issues/3953) you may shave a +bit off startup time by using a pure Python import: add the code below to, for +example, `~/.config/xonsh/mise.py` config file and `import mise` it in `~/.config/xonsh/rc.xsh`: ```python from pathlib import Path @@ -327,9 +340,10 @@ Or continue to use `rc.xsh`/`.xonshrc`: echo 'execx($(~/bin/mise activate xonsh))' >> ~/.config/xonsh/rc.xsh # or ~/.xonshrc ``` -Given that `mise` replaces both shell env `$PATH` and OS environ `PATH`, watch out that your configs don't have these -two set differently (might throw `os.environ['PATH'] = xonsh.built_ins.XSH.env.get_detyped('PATH')` at the end of a -config to make sure they match) +Given that `mise` replaces both shell env `$PATH` and OS environ `PATH`, watch out that your configs +don't have these two set differently (might +throw `os.environ['PATH'] = xonsh.built_ins.XSH.env.get_detyped('PATH')` at the end of a config to +make sure they match) ### Elvish @@ -349,16 +363,20 @@ edit:add-var mise~ {|@args| mise:mise $@args } ### Something else? -Adding a new shell is not hard at all since very little shell code is in this project. -[See here](https://github.com/jdx/mise/tree/main/src/shell) for how the others are implemented. If your shell isn't -currently supported I'd be happy to help you get yours integrated. +Adding a new shell is not hard at all since very little shell code is +in this project. +[See here](https://github.com/jdx/mise/tree/main/src/shell) for how +the others are implemented. If your shell isn't currently supported +I'd be happy to help you get yours integrated. ## Autocompletion -::: tip Some installation methods automatically install autocompletion scripts. ::: +::: tip +Some installation methods automatically install autocompletion scripts. +::: -The [`mise completion`](/cli/completion.html) command can generate autocompletion scripts for your shell. This requires -`usage` to be installed. If you don't have it, install it with: +The [`mise completion`](/cli/completion.html) command can generate autocompletion scripts for your shell. +This requires `usage` to be installed. If you don't have it, install it with: ```shell mise use -g usage @@ -397,8 +415,8 @@ Then source your shell's rc file or restart your shell. ## Uninstalling -Use `mise implode` to uninstall mise. This will remove the mise binary and all of its data. Use `mise implode --help` -for more information. +Use `mise implode` to uninstall mise. This will remove the mise binary and all of its data. Use +`mise implode --help` for more information. Alternatively, manually remove the following directories to fully clean up: diff --git a/docs/lang/bun.md b/docs/lang/bun.md index ea51a23dab..d30178b508 100644 --- a/docs/lang/bun.md +++ b/docs/lang/bun.md @@ -1,7 +1,7 @@ # Bun -The following are instructions for using the bun mise core plugin. This is used when there isn't a git plugin installed -named "bun". +The following are instructions for using the bun mise core plugin. This is used when there isn't a +git plugin installed named "bun". The code for this is inside the mise repository at [`./src/plugins/core/bun.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/bun.rs). diff --git a/docs/lang/deno.md b/docs/lang/deno.md index 81b8d40fde..3208f1f60b 100644 --- a/docs/lang/deno.md +++ b/docs/lang/deno.md @@ -1,10 +1,10 @@ # Deno -The following are instructions for using the deno mise core plugin. This is used when there isn't a git plugin installed -named "deno". +The following are instructions for using the deno mise core plugin. This is used when there isn't a +git plugin installed named "deno". -If you want to use [asdf-deno](https://github.com/asdf-community/asdf-deno) then run -`mise plugins install deno https://github.com/asdf-community/asdf-deno`. +If you want to use [asdf-deno](https://github.com/asdf-community/asdf-deno) +then run `mise plugins install deno https://github.com/asdf-community/asdf-deno`. The code for this is inside the mise repository at [`./src/plugins/core/deno.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/deno.rs). diff --git a/docs/lang/erlang.md b/docs/lang/erlang.md index d367b86890..a0ca8a39e4 100644 --- a/docs/lang/erlang.md +++ b/docs/lang/erlang.md @@ -1,7 +1,7 @@ # Erlang -The following are instructions for using the erlang core plugin. This is used when there isn't a git plugin installed -named "erlang". +The following are instructions for using the erlang core plugin. +This is used when there isn't a git plugin installed named "erlang". The code for this is inside the mise repository at [`./src/plugins/core/erlang.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/erlang.rs). @@ -18,8 +18,8 @@ See available versions with `mise ls-remote erlang`. ## kerl -The plugin uses [kerl](https://github.com/kerl/kerl) under the hood to build erlang. See kerl's docs for information on -configuring kerl. +The plugin uses [kerl](https://github.com/kerl/kerl) under the hood to build erlang. +See kerl's docs for information on configuring kerl. ## Settings diff --git a/docs/lang/go.md b/docs/lang/go.md index 162ea654a8..dd6fe8deb1 100644 --- a/docs/lang/go.md +++ b/docs/lang/go.md @@ -1,24 +1,25 @@ # Go -The following are instructions for using the go mise core plugin. This is used when there isn't a git plugin installed -named "go". +The following are instructions for using the go mise core plugin. This is used when there isn't a +git plugin installed named "go". -If you want to use [asdf-golang](https://github.com/kennyp/asdf-golang) then use `mise plugins install go GIT_URL`. +If you want to use [asdf-golang](https://github.com/kennyp/asdf-golang) +then use `mise plugins install go GIT_URL`. The code for this is inside the mise repository at [`./src/plugins/core/go.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/go.rs). ## Usage -The following installs the latest version of go-1.21.x (if some version of 1.21.x is not already installed) and makes it -the global default: +The following installs the latest version of go-1.21.x (if some version of 1.21.x is not already +installed) and makes it the global default: ```sh mise use -g go@1.21 ``` -Minor go versions 1.20 and below require specifying `prefix` before the version number because the first version of each -series was released without a `.0` suffix, making 1.20 an exact version match: +Minor go versions 1.20 and below require specifying `prefix` before the version number because the +first version of each series was released without a `.0` suffix, making 1.20 an exact version match: ```sh mise use -g go@prefix:1.20 @@ -33,8 +34,9 @@ import Settings from '/components/settings.vue'; ## Default packages -mise can automatically install a default set of packages right after installing a new go version. To enable this -feature, provide a `$HOME/.default-go-packages` file that lists one packages per line, for example: +mise can automatically install a default set of packages right after installing a new go version. +To enable this feature, provide a `$HOME/.default-go-packages` file that lists one packages per +line, for example: ```text github.com/Dreamacro/clash # allows comments @@ -43,5 +45,5 @@ github.com/jesseduffield/lazygit ## `.go-version` file support -mise uses a `mise.toml` or `.tool-versions` file for auto-switching between software versions. However it can also read -go-specific version files named `.go-version`. +mise uses a `mise.toml` or `.tool-versions` file for auto-switching between software versions. +However it can also read go-specific version files named `.go-version`. diff --git a/docs/lang/java.md b/docs/lang/java.md index 1181b7f365..8f61884feb 100644 --- a/docs/lang/java.md +++ b/docs/lang/java.md @@ -1,17 +1,18 @@ # Java -The following are instructions for using the java mise core plugin. This is used when there isn't a git plugin installed -named "java". +The following are instructions for using the java mise core plugin. This is used when there isn't a +git plugin installed named "java". -If you want to use [asdf-java](https://github.com/halcyon/asdf-java) then use `mise plugins install java GIT_URL`. +If you want to use [asdf-java](https://github.com/halcyon/asdf-java) +then use `mise plugins install java GIT_URL`. The code for this is inside the mise repository at [`./src/plugins/core/java.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/java.rs). ## Usage -The following installs the latest version of openjdk-21.x (if some version of openjdk-21.x is not already installed) and -makes it the global default: +The following installs the latest version of openjdk-21.x (if some version of openjdk-21.x is +not already installed) and makes it the global default: ```sh mise use -g java@openjdk-21 @@ -20,18 +21,20 @@ mise use -g java@21 # alternate shorthands for openjdk-only See available versions with `mise ls-remote java`. -::: warning Note that shorthand versions (like `21` in the example) use `OpenJDK` as the vendor. The OpenJDK versions -will only be updated for a 6-month period. Updates and security patches will not be available after this short period. -This also applies for LTS versions. Also see for more information. ::: +::: warning +Note that shorthand versions (like `21` in the example) use `OpenJDK` as the vendor. +The OpenJDK versions will only be updated for a 6-month period. Updates and security patches will not be available after this short period. This also applies for LTS versions. Also see for more information. +::: ## Tool Options -The following [tool-options](/dev-tools/#tool-options) are available for the `java` backend—these go in `[tools]` in -`mise.toml`. +The following [tool-options](/dev-tools/#tool-options) are available for the `java` backend—these +go in `[tools]` in `mise.toml`. ### `release_type` -The `release_type` option allows you to specify the type of release to install. The following values are supported: +The `release_type` option allows you to specify the type of release to install. The following values +are supported: - `ga` (default): General Availability release - `ea`: Early Access release @@ -45,7 +48,8 @@ The `release_type` option allows you to specify the type of release to install. Some applications in macOS rely on `/usr/libexec/java_home` to find installed Java runtimes. -To integrate an installed Java runtime with macOS run the following commands for the proper version (e.g. openjdk-21). +To integrate an installed Java runtime with macOS run the following commands for the proper +version (e.g. openjdk-21). ```sh sudo mkdir /Library/Java/JavaVirtualMachines/openjdk-21.jdk @@ -58,10 +62,11 @@ sudo ln -s ~/.local/share/mise/installs/java/openjdk-21/Contents /Library/Java/J The Java core plugin supports the idiomatic version files `.java-version` and `.sdkmanrc`. -For `.sdkmanrc` files, mise will try to map the vendor and version to the appropriate version string. For example, the -version `20.0.2-tem` will be mapped to `temurin-20.0.2`. Due to Azul's Zulu versioning, the version `11.0.12-zulu` will -be mapped to the major version `zulu-11`. Not all vendors available in SDKMAN are supported by mise. The following -vendors are NOT supported: `bsg` ( Bisheng), `graal` (GraalVM), `nik` (Liberica NIK). +For `.sdkmanrc` files, mise will try to map the vendor and version to the appropriate version +string. For example, the version `20.0.2-tem` will be mapped to `temurin-20.0.2`. Due to Azul's Zulu +versioning, the version `11.0.12-zulu` will be mapped to the major version `zulu-11`. Not all +vendors available in SDKMAN are supported by mise. The following vendors are NOT supported: `bsg` ( +Bisheng), `graal` (GraalVM), `nik` (Liberica NIK). In case an unsupported version of java is needed, some manual work is required: @@ -82,8 +87,8 @@ ln -s ~/.sdkman/candidates/java/21.0.1-open ~/.local/share/mise/installs/java/21 cp ~/.local/share/mise/installs/java/21.0.1-open/lib/libjli.dylib ~/.local/share/mise/installs/java/21.0.1-open/Contents/MacOS/libjli.dylib ``` -4. Don't forget to make sure the cache is blocked and valid, by making sure an **empty** directory **exists** for your - version in the [mise cache](https://mise.jdx.dev/directories.html#cache-mise): e.g. +4. Don't forget to make sure the cache is blocked and valid, by making sure an **empty** directory **exists** for your version in the [mise cache](https://mise.jdx.dev/directories.html#cache-mise): + e.g. ```sh $ ls -R $MISE_CACHE_DIR/java diff --git a/docs/lang/node.md b/docs/lang/node.md index 03b1d72cf5..ed050b8177 100644 --- a/docs/lang/node.md +++ b/docs/lang/node.md @@ -1,17 +1,17 @@ # Node -The following are instructions for using the node mise core plugin. This is used when there isn't a git plugin installed -named "node". +The following are instructions for using the node mise core plugin. This is used when there isn't a +git plugin installed named "node". -If you want to use [asdf-nodejs](https://github.com/asdf-vm/asdf-nodejs) then run -`mise plugins install node https://github.com/asdf-vm/asdf-nodejs` +If you want to use [asdf-nodejs](https://github.com/asdf-vm/asdf-nodejs) +then run `mise plugins install node https://github.com/asdf-vm/asdf-nodejs` -The code for this is inside the mise repository at -[`./src/plugins/core/node.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/node.rs). +The code for this is inside the mise repository at [`./src/plugins/core/node.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/node.rs). ## Usage -The following installs the latest version of node-20.x and makes it the global default: +The following installs the latest version of node-20.x and makes it the global +default: ```sh mise use -g node@20 @@ -19,8 +19,8 @@ mise use -g node@20 ## Requirements -See [BUILDING.md](https://github.com/nodejs/node/blob/main/BUILDING.md#building-nodejs-on-supported-platforms) in node's -documentation for required system dependencies. +See [BUILDING.md](https://github.com/nodejs/node/blob/main/BUILDING.md#building-nodejs-on-supported-platforms) in node's documentation for +required system dependencies. ## Settings @@ -34,21 +34,20 @@ import Settings from '/components/settings.vue'; - `MISE_NODE_VERIFY` [bool]: Verify the downloaded assets using GPG. Defaults to `true`. - `MISE_NODE_NINJA` [bool]: Use ninja instead of make to compile node. Defaults to `true` if installed. - `MISE_NODE_CONCURRENCY` [uint]: How many jobs should be used in compilation. Defaults to half the computer cores -- `MISE_NODE_DEFAULT_PACKAGES_FILE` [string]: location of default packages file, defaults to - `$HOME/.default-npm-packages` +- `MISE_NODE_DEFAULT_PACKAGES_FILE` [string]: location of default packages file, defaults to `$HOME/.default-npm-packages` - `MISE_NODE_CFLAGS` [string]: Additional CFLAGS options (e.g., to override -O3). - `MISE_NODE_CONFIGURE_OPTS` [string]: Additional `./configure` options. - `MISE_NODE_MAKE_OPTS` [string]: Additional `make` options. - `MISE_NODE_MAKE_INSTALL_OPTS` [string]: Additional `make install` options. -- `MISE_NODE_COREPACK` [bool]: Installs the default corepack shims after installing any node version that ships with - [corepack](https://github.com/nodejs/corepack). +- `MISE_NODE_COREPACK` [bool]: Installs the default corepack shims after installing any node version that ships with [corepack](https://github.com/nodejs/corepack). -::: info TODO: these env vars should be migrated to compatible settings in the future. ::: +::: info +TODO: these env vars should be migrated to compatible settings in the future. +::: ## Default node packages -mise-node can automatically install a default set of npm packages right after installing a node version. To enable this -feature, provide a `$HOME/.default-npm-packages` file that lists one package per line, for example: +mise-node can automatically install a default set of npm packages right after installing a node version. To enable this feature, provide a `$HOME/.default-npm-packages` file that lists one package per line, for example: ```text lodash @@ -60,20 +59,19 @@ You can specify a non-default location of this file by setting a `MISE_NODE_DEFA ## `.nvmrc` and `.node-version` support -mise uses a `mise.toml` or `.tool-versions` file for auto-switching between software versions. To ease migration, you -can have also have it read an existing `.nvmrc` or `.node-version` file to find out what version of Node.js should be -used. This will be used if `node` isn't defined in `mise.toml`/`.tool-versions`. +mise uses a `mise.toml` or `.tool-versions` file for auto-switching between software versions. To ease migration, you can have also have it read an existing `.nvmrc` or `.node-version` file to find out what version of Node.js should be used. This will be used if `node` isn't defined in `mise.toml`/`.tool-versions`. ## "nodejs" -> "node" Alias -You cannot install/use a plugin named "nodejs". If you attempt this, mise will just rename it to "node". See the -[FAQ](https://github.com/jdx/mise#what-is-the-difference-between-nodejs-and-node-or-golang-and-go) for an explanation. +You cannot install/use a plugin named "nodejs". If you attempt this, mise will just rename it to +"node". See the [FAQ](https://github.com/jdx/mise#what-is-the-difference-between-nodejs-and-node-or-golang-and-go) +for an explanation. ## Unofficial Builds -Nodejs.org offers a set of [unofficial builds](https://unofficial-builds.nodejs.org/) which are compatible with some -platforms that are not supported by the official binaries. These are a nice alternative to compiling from source for -these platforms. +Nodejs.org offers a set of [unofficial builds](https://unofficial-builds.nodejs.org/) which are +compatible with some platforms that are not supported by the official binaries. These are a nice alternative to +compiling from source for these platforms. To use, first set the mirror url to point to the unofficial builds: @@ -81,9 +79,9 @@ To use, first set the mirror url to point to the unofficial builds: mise settings node.mirror_url=https://unofficial-builds.nodejs.org/download/release/ ``` -If your goal is to simply support an alternative arch/os like linux-loong64 or linux-armv6l, this is all that is -required. Node also provides flavors such as musl or glibc-217 (an older glibc version than what the official binaries -are built with). +If your goal is to simply support an alternative arch/os like linux-loong64 or linux-armv6l, this is +all that is required. Node also provides flavors such as musl or glibc-217 (an older glibc version +than what the official binaries are built with). To use these, set `node.flavor`: diff --git a/docs/lang/python.md b/docs/lang/python.md index b390d55278..e701751453 100644 --- a/docs/lang/python.md +++ b/docs/lang/python.md @@ -1,14 +1,16 @@ # Python -The following are instructions for using the python mise core plugin. The core plugin will be used so long as no plugin -is manually installed named "python" using `mise plugins install python [GIT_URL]`. +The following are instructions for using the python mise core plugin. The core plugin will be used +so long as no plugin is manually +installed named "python" using `mise plugins install python [GIT_URL]`. -The code for this is inside of the mise repository at -[`./src/plugins/core/python.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/python.rs). +The code for this is inside of the mise repository +at [`./src/plugins/core/python.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/python.rs). ## Usage -The following installs the latest version of python-3.11.x and makes it the global default: +The following installs the latest version of python-3.11.x and makes it the global +default: ```sh mise use -g python@3.11 @@ -26,7 +28,8 @@ $ python3.11 -V ## Settings -`python-build` already has a [handful of settings](https://github.com/pyenv/pyenv/tree/master/plugins/python-build), in +`python-build` already has +a [handful of settings](https://github.com/pyenv/pyenv/tree/master/plugins/python-build), in additional to that python in mise has a few extra configuration variables. Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable. @@ -38,44 +41,53 @@ import Settings from '/components/settings.vue'; ## Default Python packages -mise can automatically install a default set of Python packages with pip right after installing a Python version. To -enable this feature, provide a `$HOME/.default-python-packages` file that lists one package per line, for example: +mise can automatically install a default set of Python packages with pip right after installing a +Python version. To enable this feature, provide a `$HOME/.default-python-packages` file that lists +one package per line, for example: ```text ansible pipenv ``` -You can specify a non-default location of this file by setting a `MISE_PYTHON_DEFAULT_PACKAGES_FILE` variable. +You can specify a non-default location of this file by setting a `MISE_PYTHON_DEFAULT_PACKAGES_FILE` +variable. ## Precompiled python binaries -By default, mise will download [precompiled binaries](https://github.com/astral-sh/python-build-standalone) for python -instead of compiling them with python-build. This makes installing python much faster. +By default, mise will +download [precompiled binaries](https://github.com/astral-sh/python-build-standalone) +for python instead of compiling them with python-build. This makes installing python much faster. -In addition to being faster, it also means you don't have to install all of the system dependencies either. +In addition to being faster, it also means you don't have to install all of the system dependencies +either. -That said, there are some [quirks](https://github.com/astral-sh/python-build-standalone/blob/main/docs/quirks.rst) with -the precompiled binaries to be aware of. +That said, there are +some [quirks](https://github.com/astral-sh/python-build-standalone/blob/main/docs/quirks.rst) +with the precompiled binaries to be aware of. If you'd like to disable these binaries, set `mise settings python.compile=1`. -These binaries may not work on older CPUs however you may opt into binaries which are more compatible with older CPUs by -setting `MISE_PYTHON_PRECOMPILED_ARCH` with a different version. See - for more information on this option. Set it to -"x86_64" for the most compatible binaries. +These binaries may not work on older CPUs however you may opt into binaries which +are more compatible with older CPUs by setting `MISE_PYTHON_PRECOMPILED_ARCH` with +a different version. See for +more information +on this option. Set it to "x86_64" for the most compatible binaries. ## python-build -Optionally, mise uses [python-build](https://github.com/pyenv/pyenv/tree/master/plugins/python-build) (part of pyenv) to -compile python runtimes, you need to ensure its -[dependencies](https://github.com/pyenv/pyenv/wiki#suggested-build-environment) are installed before installing python -with python-build. +Optionally, mise +uses [python-build](https://github.com/pyenv/pyenv/tree/master/plugins/python-build) (part of pyenv) +to compile python runtimes, +you need to ensure +its [dependencies](https://github.com/pyenv/pyenv/wiki#suggested-build-environment) are installed +before installing python with +python-build. ## Troubleshooting errors with Homebrew -If you normally use Homebrew and you see errors regarding OpenSSL, your best bet might be using the following command to -install Python: +If you normally use Homebrew and you see errors regarding OpenSSL, +your best bet might be using the following command to install Python: ```sh CFLAGS="-I$(brew --prefix openssl)/include" \ @@ -83,10 +95,15 @@ LDFLAGS="-L$(brew --prefix openssl)/lib" \ mise install python@latest; ``` -Homebrew installs its own OpenSSL version, which may collide with system-expected ones. You could even add that to your -`.profile`, `.bashrc`, `.zshrc`... to avoid setting them every time +Homebrew installs its own OpenSSL version, which may collide with system-expected ones. +You could even add that to your +`.profile`, +`.bashrc`, +`.zshrc`... +to avoid setting them every time -Additionally, if you encounter issues with python-build, you may benefit from unlinking pkg-config prior to install +Additionally, if you encounter issues with python-build, +you may benefit from unlinking pkg-config prior to install ([reason](https://github.com/pyenv/pyenv/issues/2823#issuecomment-1769081965)). ```sh @@ -107,7 +124,8 @@ brew link pkg-config ## Automatic virtualenv activation -Python comes with virtualenv support built in, use it with `mise.toml` configuration like one of the following: +Python comes with virtualenv support built in, use it with `mise.toml` configuration like +one of the following: ```toml [tools] diff --git a/docs/lang/ruby.md b/docs/lang/ruby.md index da8fd81e88..e76711b5e5 100644 --- a/docs/lang/ruby.md +++ b/docs/lang/ruby.md @@ -1,32 +1,34 @@ # Ruby -The following are instructions for using the ruby mise core plugin. This is used when there isn't a git plugin installed -named "ruby". +The following are instructions for using the ruby mise core plugin. This is used when there isn't a +git plugin installed named "ruby". -If you want to use [asdf-ruby](https://github.com/asdf-vm/asdf-ruby) then use `mise plugins install ruby GIT_URL`. +If you want to use [asdf-ruby](https://github.com/asdf-vm/asdf-ruby) +then use `mise plugins install ruby GIT_URL`. The code for this is inside the mise repository at [`./src/plugins/core/ruby.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/ruby.rs). ## Usage -The following installs the latest version of ruby-3.2.x (if some version of 3.2.x is not already installed) and makes it -the global default: +The following installs the latest version of ruby-3.2.x (if some version of 3.2.x is not already +installed) and makes it the global default: ```sh mise use -g ruby@3.2 ``` -Behind the scenes, mise uses [`ruby-build`](https://github.com/rbenv/ruby-build) to compile ruby from source. Ensure -that you have the necessary [dependencies](https://github.com/rbenv/ruby-build/wiki#suggested-build-environment) -installed. You can check its [README](https://github.com/rbenv/ruby-build/blob/master/README.md) for additional settings -and some troubleshooting. +Behind the scenes, mise uses [`ruby-build`](https://github.com/rbenv/ruby-build) to compile ruby +from source. Ensure that you have the necessary +[dependencies](https://github.com/rbenv/ruby-build/wiki#suggested-build-environment) installed. +You can check its [README](https://github.com/rbenv/ruby-build/blob/master/README.md) for additional settings and some +troubleshooting. ## Settings `ruby-build` already has a -[handful of settings](https://github.com/rbenv/ruby-build?tab=readme-ov-file#custom-build-configuration), in additional -to that mise has a few extra settings: +[handful of settings](https://github.com/rbenv/ruby-build?tab=readme-ov-file#custom-build-configuration), +in additional to that mise has a few extra settings: