From 7f6c51d4f7a7fdb797ad93b8f538cc903757749f Mon Sep 17 00:00:00 2001 From: jdx <216188+jdx@users.noreply.github.com> Date: Sat, 1 Jun 2024 22:57:56 +0000 Subject: [PATCH] chore: migrate docs repo into this repo (#2237) --- .github/workflows/docs.yml | 42 ++ .github/workflows/release.yml | 26 +- .idea/mise.iml | 8 +- .markdownlint.json | 1 + .mise/tasks/release-docs | 17 + docs/.gitignore | 176 +++++++ docs/.mise.toml | 12 + docs/.vitepress/config.ts | 151 ++++++ docs/LICENSE | 21 + docs/README.md | 3 + docs/about.md | 42 ++ docs/bun.lockb | Bin 0 -> 69822 bytes docs/bun.md | 1 - docs/cache-behavior.md | 31 ++ docs/cli/global-flags.md | 28 ++ docs/{cli-reference.md => cli/index.md} | 0 docs/config.ts | 1 + docs/configuration.md | 591 ++++++++++++++++++++++++ docs/contact.md | 17 + docs/continuous-integration.md | 72 +++ docs/contributing.md | 174 +++++++ docs/demo.md | 7 + docs/deno.md | 1 - docs/dev-tools/aliases.md | 28 ++ docs/dev-tools/backends/asdf.md | 22 + docs/dev-tools/backends/cargo.md | 61 +++ docs/dev-tools/backends/go.md | 30 ++ docs/dev-tools/backends/index.md | 16 + docs/dev-tools/backends/npm.md | 33 ++ docs/dev-tools/backends/pipx.md | 54 +++ docs/dev-tools/backends/ubi.md | 42 ++ docs/dev-tools/comparison-to-asdf.md | 106 +++++ docs/dev-tools/index.md | 122 +++++ docs/dev-tools/shims.md | 194 ++++++++ docs/directories.md | 83 ++++ docs/direnv.md | 91 ++++ docs/environments.md | 129 ++++++ docs/errors.md | 3 + docs/faq.md | 256 ++++++++++ docs/getting-started.md | 421 +++++++++++++++++ docs/go.md | 1 - docs/how-i-use-mise.md | 122 +++++ docs/ide-integration.md | 159 +++++++ docs/index.md | 39 ++ docs/java.md | 1 - docs/lang/bun.md | 18 + docs/lang/deno.md | 21 + docs/lang/erlang.md | 22 + docs/lang/go.md | 101 ++++ docs/lang/java.md | 76 +++ docs/lang/node.md | 59 +++ docs/lang/python.md | 195 ++++++++ docs/lang/ruby.md | 72 +++ docs/lang/rust.md | 40 ++ docs/lefthook.yml | 6 + docs/node.md | 1 - docs/package.json | 13 + docs/paranoid.md | 51 ++ docs/plugins.md | 48 ++ docs/profiles.md | 39 ++ docs/project-roadmap.md | 33 ++ docs/public/android-chrome-192x192.png | Bin 0 -> 5311 bytes docs/public/android-chrome-512x512.png | Bin 0 -> 25069 bytes docs/public/apple-touch-icon.png | Bin 0 -> 4792 bytes docs/public/favicon-16x16.png | Bin 0 -> 262 bytes docs/public/favicon-32x32.png | Bin 0 -> 462 bytes docs/public/favicon.ico | Bin 0 -> 15406 bytes docs/public/site.webmanifest | 1 + docs/python.md | 1 - docs/rtx.md | 51 ++ docs/ruby.md | 1 - docs/tasks/index.md | 22 + docs/tasks/running-tasks.md | 112 +++++ docs/tasks/script-tasks.md | 61 +++ docs/tasks/toml-tasks.md | 43 ++ docs/team.md | 61 +++ docs/templates.md | 31 ++ docs/tips-and-tricks.md | 82 ++++ scripts/publish-r2.sh | 2 +- scripts/publish-s3.sh | 6 +- scripts/release.sh | 24 +- src/cli/render_help.rs | 12 +- src/shell/nushell.rs | 8 +- src/toolset/tool_version_request.rs | 3 + 84 files changed, 4692 insertions(+), 59 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100755 .mise/tasks/release-docs create mode 100644 docs/.gitignore create mode 100644 docs/.mise.toml create mode 100644 docs/.vitepress/config.ts create mode 100644 docs/LICENSE create mode 100644 docs/README.md create mode 100644 docs/about.md create mode 100755 docs/bun.lockb delete mode 100644 docs/bun.md create mode 100644 docs/cache-behavior.md create mode 100644 docs/cli/global-flags.md rename docs/{cli-reference.md => cli/index.md} (100%) create mode 120000 docs/config.ts create mode 100644 docs/configuration.md create mode 100644 docs/contact.md create mode 100644 docs/continuous-integration.md create mode 100644 docs/contributing.md create mode 100644 docs/demo.md delete mode 100644 docs/deno.md create mode 100644 docs/dev-tools/aliases.md create mode 100644 docs/dev-tools/backends/asdf.md create mode 100644 docs/dev-tools/backends/cargo.md create mode 100644 docs/dev-tools/backends/go.md create mode 100644 docs/dev-tools/backends/index.md create mode 100644 docs/dev-tools/backends/npm.md create mode 100644 docs/dev-tools/backends/pipx.md create mode 100644 docs/dev-tools/backends/ubi.md create mode 100644 docs/dev-tools/comparison-to-asdf.md create mode 100644 docs/dev-tools/index.md create mode 100644 docs/dev-tools/shims.md create mode 100644 docs/directories.md create mode 100644 docs/direnv.md create mode 100644 docs/environments.md create mode 100644 docs/errors.md create mode 100644 docs/faq.md create mode 100644 docs/getting-started.md delete mode 100644 docs/go.md create mode 100644 docs/how-i-use-mise.md create mode 100644 docs/ide-integration.md create mode 100644 docs/index.md delete mode 100644 docs/java.md create mode 100644 docs/lang/bun.md create mode 100644 docs/lang/deno.md create mode 100644 docs/lang/erlang.md create mode 100644 docs/lang/go.md create mode 100644 docs/lang/java.md create mode 100644 docs/lang/node.md create mode 100644 docs/lang/python.md create mode 100644 docs/lang/ruby.md create mode 100644 docs/lang/rust.md create mode 100644 docs/lefthook.yml delete mode 100644 docs/node.md create mode 100644 docs/package.json create mode 100644 docs/paranoid.md create mode 100644 docs/plugins.md create mode 100644 docs/profiles.md create mode 100644 docs/project-roadmap.md create mode 100755 docs/public/android-chrome-192x192.png create mode 100755 docs/public/android-chrome-512x512.png create mode 100755 docs/public/apple-touch-icon.png create mode 100755 docs/public/favicon-16x16.png create mode 100755 docs/public/favicon-32x32.png create mode 100755 docs/public/favicon.ico create mode 100755 docs/public/site.webmanifest delete mode 100644 docs/python.md create mode 100644 docs/rtx.md delete mode 100644 docs/ruby.md create mode 100644 docs/tasks/index.md create mode 100644 docs/tasks/running-tasks.md create mode 100644 docs/tasks/script-tasks.md create mode 100644 docs/tasks/toml-tasks.md create mode 100644 docs/team.md create mode 100644 docs/templates.md create mode 100644 docs/tips-and-tricks.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..2e2e1ccd42 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,42 @@ +name: mise-docs + +on: + push: + paths: + - "docs/**" + branches: + - main + pull_request: + paths: + - "docs/**" + branches: + - main + +concurrency: + group: mise-docs-release-${{ github.head_ref }} + cancel-in-progress: true + +env: + MISE_EXPERIMENTAL: 1 + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # for lastUpdated + - uses: jdx/mise-action@v2 + with: + install_args: bun + working_directory: docs + - run: bun install + working-directory: docs + - run: bun run docs:build + working-directory: docs + - if: github.event_name == 'push' && github.ref == 'refs/heads/main' + run: mise run release-docs + working-directory: docs + env: + AWS_ACCESS_KEY_ID: ${{ secrets.CLOUDFLARE_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.CLOUDFLARE_SECRET_ACCESS_KEY }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index dad6c35ab4..eee9d41d1b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -3,7 +3,7 @@ name: release on: push: tags: ["v*"] - branches: ["release", "win"] + branches: ["release", "win", "docs"] workflow_dispatch: concurrency: @@ -250,20 +250,18 @@ jobs: - build-tarball-win steps: - uses: actions/checkout@v4 + - uses: crazy-max/ghaction-import-gpg@v6 with: - path: mise - - uses: actions/checkout@v4 - with: - repository: jdx/mise-docs - path: mise-docs - token: ${{ secrets.RTX_GITHUB_BOT_TOKEN }} + gpg_private_key: ${{ secrets.MISE_GPG_KEY }} + git_user_signingkey: true + git_commit_gpgsign: true - name: cache zipsign id: cache-zipsign uses: actions/cache@v4 with: path: ~/.cargo/bin/zipsign key: cargo-zipsign - - run: ./mise/scripts/setup-zipsign.sh + - run: ./scripts/setup-zipsign.sh env: ZIPSIGN: ${{ secrets.ZIPSIGN }} - name: Install fd-find @@ -281,12 +279,6 @@ jobs: with: key: ${{ secrets.RTX_SSH_KEY }} known_hosts: ${{ secrets.RTX_KNOWN_HOSTS_AUR }} - - uses: crazy-max/ghaction-import-gpg@v6 - with: - gpg_private_key: ${{ secrets.MISE_GPG_KEY }} - git_user_signingkey: true - git_commit_gpgsign: true - workdir: mise-docs - uses: actions/download-artifact@v4 with: { path: artifacts } - run: ls -R artifacts @@ -299,16 +291,12 @@ jobs: mise-v*.zip merge-multiple: true - run: ls -R artifacts - - run: mise/scripts/release.sh + - run: scripts/release.sh env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_TOKEN }} NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} CLOUDFLARE_ACCESS_KEY_ID: ${{ secrets.CLOUDFLARE_ACCESS_KEY_ID }} CLOUDFLARE_SECRET_ACCESS_KEY: ${{ secrets.CLOUDFLARE_SECRET_ACCESS_KEY }} - - name: mise-docs push - if: startsWith(github.event.ref, 'refs/tags/v') - run: git push - working-directory: mise-docs - name: GitHub Release Assets uses: softprops/action-gh-release@v2 if: startsWith(github.event.ref, 'refs/tags/v') diff --git a/.idea/mise.iml b/.idea/mise.iml index 26265d4cb4..ff4628d837 100644 --- a/.idea/mise.iml +++ b/.idea/mise.iml @@ -26,17 +26,17 @@ - - + + - + - \ No newline at end of file + diff --git a/.markdownlint.json b/.markdownlint.json index a36edfc88f..a69775f0a1 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,6 +1,7 @@ { "MD004": false, "MD013": false, + "MD029": false, "MD033": false, "MD040": false, "MD041": false diff --git a/.mise/tasks/release-docs b/.mise/tasks/release-docs new file mode 100755 index 0000000000..dcd3398040 --- /dev/null +++ b/.mise/tasks/release-docs @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +set -xeuo pipefail + +export AWS_REGION=auto +export AWS_ENDPOINT_URL=https://6e243906ff257b965bcae8025c2fc344.r2.cloudflarestorage.com + +bun run docs:build + +if [ $((RANDOM % 30)) -eq 0 ]; then + # delete old assets only roughly 1/30 times + # deleting old assets can break the site for people currently on it + # but it's also good to keep things tidy + aws s3 rm --recursive s3://mise/assets/ + aws s3 rm --recursive --exclude "*" --include "*.html" s3://mise/ +fi + +aws s3 cp --recursive .vitepress/dist s3://mise/ diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..2c8e6b2995 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,176 @@ +### macOS ### +# General +.DS_Store +.AppleDouble +.LSOverride + +# Icon must end with two \r +Icon + + +# Thumbnails +._* + +# Files that might appear in the root of a volume +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent + +# Directories potentially created on remote AFP share +.AppleDB +.AppleDesktop +Network Trash Folder +Temporary Items +.apdisk + +### macOS Patch ### +# iCloud generated files +*.icloud + +### Node ### +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* +.pnpm-debug.log* + +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# Snowpack dependency directory (https://snowpack.dev/) +web_modules/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Optional stylelint cache +.stylelintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variable files +.env +.env.development.local +.env.test.local +.env.production.local +.env.local + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next +out + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# vuepress v2.x temp and cache directory +.temp + +# Docusaurus cache and generated files +.docusaurus + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +# yarn v2 +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* + +### Node Patch ### +# Serverless Webpack directories +.webpack/ + +# Optional stylelint cache + +# SvelteKit build / generate output +.svelte-kit + +# VitePress +.vitepress/cache +.vitepress/dist diff --git a/docs/.mise.toml b/docs/.mise.toml new file mode 100644 index 0000000000..5da73af9e0 --- /dev/null +++ b/docs/.mise.toml @@ -0,0 +1,12 @@ +tasks.dev = "bun run docs:dev" +tasks.build = "bun run docs:build" + +[tasks."commit-and-push"] +depends = ["build"] +run = [ + "git ci -pm docs", + "git push", +] + +[tools] +bun = 'latest' diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts new file mode 100644 index 0000000000..aa3b251df1 --- /dev/null +++ b/docs/.vitepress/config.ts @@ -0,0 +1,151 @@ +import { defineConfig } from 'vitepress' + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + title: "mise-en-place", + description: "mise-en-place documentation", + lang: 'en-US', + lastUpdated: true, + appearance: 'dark', + sitemap: { + hostname: 'https://mise.jdx.dev', + }, + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + outline: 'deep', + nav: [ + { text: 'Dev Tools', link: '/dev-tools/' }, + { text: 'Environments', link: '/environments' }, + { text: 'Tasks', link: '/tasks/' }, + ], + sidebar: [ + { text: 'Getting Started', link: '/getting-started' }, + { text: 'About', link: '/about' }, + { text: 'Coming from rtx', link: '/rtx' }, + { text: 'Configuration', link: '/configuration' }, + { text: 'Continuous Integration', link: '/continuous-integration' }, + { text: 'Demo', link: '/demo' }, + { text: 'FAQs', link: '/faq' }, + { text: 'How I Use mise', link: '/how-i-use-mise' }, + { text: 'IDE Integration', link: '/ide-integration' }, + { text: 'Paranoid', link: '/paranoid' }, + { text: 'Registry', link: '/registry' }, + { text: 'Plugins', link: '/plugins' }, + { text: 'Team', link: '/team' }, + { text: 'Contributing', link: '/contributing' }, + { text: 'Tips & Tricks', link: '/tips-and-tricks' }, + { + text: 'Dev Tools', + link: '/dev-tools/', + items: [ + { text: 'Aliases', link: '/dev-tools/aliases' }, + { text: 'Comparison to asdf', link: '/dev-tools/comparison-to-asdf' }, + { text: 'Shims', link: '/dev-tools/shims' }, + { + text: 'Backends', + link: '/dev-tools/backends/', + items: [ + { text: 'asdf', link: '/dev-tools/backends/asdf' }, + { text: 'cargo', link: '/dev-tools/backends/cargo' }, + { text: 'go', link: '/dev-tools/backends/go' }, + { text: 'npm', link: '/dev-tools/backends/npm' }, + { text: 'pipx', link: '/dev-tools/backends/pipx' }, + { text: 'ubi', link: '/dev-tools/backends/ubi' }, + ] + } + ], + }, + { + text: 'Environments', + link: '/environments', + items: [ + { text: 'direnv', link: '/direnv' }, + { text: 'Profiles', link: '/profiles' }, + { text: 'Templates', link: '/templates' }, + ], + }, + { + text: 'Tasks', + link: '/tasks/', + items: [ + {text: 'Running Tasks', link: '/tasks/running-tasks'}, + {text: 'Script Tasks', link: '/tasks/script-tasks'}, + {text: 'TOML Tasks', link: '/tasks/toml-tasks'}, + ], + }, + { + text: 'Languages', + items: [ + { text: 'Bun', link: '/lang/bun' }, + { text: 'Deno', link: '/lang/deno' }, + { text: 'Erlang', link: '/lang/erlang' }, + { text: 'Go', link: '/lang/go' }, + { text: 'Java', link: '/lang/java' }, + { text: 'Node.js', link: '/lang/node' }, + { text: 'Python', link: '/lang/python' }, + { text: 'Ruby', link: '/lang/ruby' }, + { text: 'Rust', link: '/lang/rust' }, + ] + }, + { + text: 'Internals', + items: [ + { text: 'Cache Behavior', link: '/cache-behavior' }, + { text: 'Directory Structure', link: '/directories' }, + { text: 'Project Roadmap', link: '/project-roadmap' }, + ], + }, + { + text: 'CLI Reference', + link: '/cli/', + items: [ + { text: 'Global Flags', link: '/cli/global-flags' } + ] + }, + ], + + socialLinks: [ + { icon: 'github', link: 'https://github.com/jdx/mise' } + ], + + editLink: { + pattern: 'https://github.com/jdx/mise/edit/main/docs/:path', + }, + search: { + provider: 'algolia', + options: { + indexName: 'rtx', + appId: '1452G4RPSJ', + apiKey: 'ad09b96a7d2a30eddc2771800da7a1cf', + insights: true, + } + }, + footer: { + message: 'Licensed under the MIT License. Maintained by @jdx and friends.', + copyright: 'Copyright © 2024 @jdx', + }, + carbonAds: { + code: 'CWYIPKQN', + placement: 'misejdxdev', + }, + }, + markdown: { + // languages: [ + // "elisp" + // ] + }, + head: [ + [ + 'script', + { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=G-B69G389C8T' } + ], + [ + 'script', + {}, + `window.dataLayer = window.dataLayer || []; + function gtag(){dataLayer.push(arguments);} + gtag('js', new Date()); + gtag('config', 'G-B69G389C8T');` + ] + ], +}) diff --git a/docs/LICENSE b/docs/LICENSE new file mode 100644 index 0000000000..a548a770b3 --- /dev/null +++ b/docs/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 jdx + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..6af9b4bb48 --- /dev/null +++ b/docs/README.md @@ -0,0 +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/). diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000000..65fa0ad0a9 --- /dev/null +++ b/docs/about.md @@ -0,0 +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` 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` 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. + +## 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`. diff --git a/docs/bun.lockb b/docs/bun.lockb new file mode 100755 index 0000000000000000000000000000000000000000..3298355f671d5b0f90cad0531bc253b16920d8e9 GIT binary patch literal 69822 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. It stores +the list of versions available for that plugin (`mise ls-remote `), the legacy 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)). + +```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. + +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/cli/global-flags.md b/docs/cli/global-flags.md new file mode 100644 index 0000000000..d699cd0b49 --- /dev/null +++ b/docs/cli/global-flags.md @@ -0,0 +1,28 @@ +# Global Flags + +These flags are available for all commands in the CLI. They may not always +do anything though. + +## `-C, --cd ` + +Change directory before running command + +## `-q, --quiet` + +Suppress non-error messages + +## `-v, --verbose...` + +Show extra output (use -vv for even more) + +## `-y, --yes` + +Answer yes to all confirmation prompts + +## `-h, --help` + +Print help (see a summary with '-h') + +## `-V, --version` + +Print version diff --git a/docs/cli-reference.md b/docs/cli/index.md similarity index 100% rename from docs/cli-reference.md rename to docs/cli/index.md diff --git a/docs/config.ts b/docs/config.ts new file mode 120000 index 0000000000..fec31cbd73 --- /dev/null +++ b/docs/config.ts @@ -0,0 +1 @@ +.vitepress/config.ts \ No newline at end of file diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000000..1bdd724fc1 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,591 @@ +# Configuration + +## `.mise.toml` + +`.mise.toml` is a new config file that replaces asdf-style `.tool-versions` files with a file +that has lot more flexibility. It supports functionality that is not possible with `.tool-versions`, +such as: + +- setting arbitrary env vars while inside the directory +- passing options to plugins like `virtualenv=".venv"` + for [python](https://github.com/jdx/mise/blob/main/docs/python.md#experimental-automatic-virtualenv-creationactivation). +- specifying custom plugin URLs + +They can use any of the following file locations (in order of precedence, top is highest): + +- `.mise.local.toml` +- `mise.local.toml` +- `.mise.$MISE_ENV.toml` +- `mise.$MISE_ENV.toml` +- `.mise.toml` +- `.mise/config.toml` +- `mise.toml` +- `mise/config.toml` +- `.config/mise.toml` +- `.config/mise/config.toml` + +See [Profiles](/profiles) for more information about `.mise.$MISE_ENV.toml` files. +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 along with their precedence. +::: + +Here is what an `.mise.toml` looks like: + +```toml +[env] +# supports arbitrary env vars so mise can be used like direnv/dotenv +NODE_ENV = 'production' + +[tools] +# specify single or multiple versions +terraform = '1.0.0' +erlang = ['23.3', '24.0'] + +# supports everything you can do with .tool-versions currently +node = ['16', 'prefix:20', 'ref:master', 'path:~/.nodes/14'] + +# send arbitrary options to the plugin, passed as: +# MISE_TOOL_OPTS__VENV=.venv +python = { version = '3.10', virtualenv = '.venv' } + +[plugins] +# specify a custom repo url +# note this will only be used if the plugin does not already exist +python = 'https://github.com/asdf-community/asdf-python' + +[alias.node] # project-local aliases +my_custom_node = '20' +``` + +`.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] +node = '20' +python = '3.10' +``` + +And `~/src/myproj/backend/.mise.toml` defines: + +```toml +[tools] +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`. + +You can also have environment specific config files like `.mise.production.toml`, see +[Profiles](/profiles) for more details. + +### `[env]` - Arbitrary Environment Variables + +See [environments](/environments). + +### `[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. + +```toml +[plugins] +elixir = "https://github.com/my-org/mise-elixir.git" +node = "https://github.com/my-org/mise-node.git#DEADBEEF" # supports specific gitref +``` + +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. + +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: + +```sh +~/.local/share/mise/installs/node/20 -> ./20.x.x +``` + +```toml +my_custom_node = '20' +``` + +## 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. + +```toml +[tools] +# global tool versions go here +# you can set these with `mise use -g` +node = 'lts' +python = ['3.10', '3.11'] + +[settings] +# plugins can read the versions files used by other version managers (if enabled by the plugin) +# for example, .nvmrc in the case of node's nvm +legacy_version_file = true # enabled by default (unlike asdf) +legacy_version_file_disable_tools = ['python'] # disable for specific tools + +# configure `mise install` to always keep the downloaded archive +always_keep_download = false # deleted after install by default +always_keep_install = false # deleted on failure by default + +# configure how frequently (in minutes) to fetch updated plugin repository changes +# this is updated whenever a new runtime is installed +# (note: this isn't currently implemented but there are plans to add it: https://github.com/jdx/mise/issues/128) +plugin_autoupdate_last_check_duration = '1 week' # set to 0 to disable updates + +# config files with these prefixes will be trusted by default +trusted_config_paths = [ + '~/work/my-trusted-projects', +] + +verbose = false # set to true to see full installation output, see `MISE_VERBOSE` +asdf_compat = false # set to true to ensure .tool-versions will be compatible with asdf, see `MISE_ASDF_COMPAT` +http_timeout = 30 # set the timeout for http requests in seconds, see `MISE_HTTP_TIMEOUT` +jobs = 4 # number of plugins or runtimes to install in parallel. The default is `4`. +raw = false # set to true to directly pipe plugins to stdin/stdout/stderr +yes = false # set to true to automatically answer yes to all prompts + +not_found_auto_install = true # see MISE_NOT_FOUND_AUTO_INSTALL +task_output = "prefix" # see Tasks Runner for more information +paranoid = false # see MISE_PARANOID + +shorthands_file = '~/.config/mise/shorthands.toml' # path to the shorthands file, see `MISE_SHORTHANDS_FILE` +disable_default_shorthands = false # disable the default shorthands, see `MISE_DISABLE_DEFAULT_SHORTHANDS` +disable_tools = ['node'] # disable specific tools, generally used to turn off core tools + +env_file = '.env' # load env vars from a dotenv file, see `MISE_ENV_FILE` + +experimental = true # enable experimental features + +# configure messages displayed when entering directories with config files +status = { missing_tools = "if_other_versions_installed", show_env = false, show_tools = false } +``` + +## 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. + +## `.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. + +Here is an example with all the supported syntax: + +```text +node 20.0.0 # comments are allowed +ruby 3 # can be fuzzy version +shellcheck latest # also supports "latest" +jq 1.6 +erlang ref:master # compile from vcs ref +go prefix:1.19 # uses the latest 1.19.x version—needed in case "1.19" is an exact match +shfmt path:./shfmt # use a custom runtime +node lts # use lts version of node (not supported by all plugins) + +node sub-2:lts # install 2 versions behind the latest lts (e.g.: 18 if lts is 20) +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. + +## 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`. + +## Legacy version files + +mise supports "legacy 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 legacy version files: + +| Plugin | "Legacy" (Idiomatic) Files | +|-----------|----------------------------------------------------| +| crystal | `.crystal-version` | +| elixir | `.exenv-version` | +| go | `.go-version`, `go.mod` | +| java | `.java-version`, `.sdkmanrc` | +| node | `.nvmrc`, `.node-version` | +| python | `.python-version` | +| ruby | `.ruby-version`, `Gemfile` | +| terraform | `.terraform-version`, `.packer-version`, `main.tf` | +| yarn | `.yarnrc` | + +In mise these are enabled by default. You can disable them +with `mise settings set legacy_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 calls these "legacy version files" so we do too. I think this is 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're 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 + +The following is a list of all of mise's settings. These can be set via `mise settings set`, +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. + +### `activate_aggressive` + +* Type: `bool` +* Env: `MISE_ACTIVATE_AGGRESSIVE` +* Default: `false` + +Pushes tools' bin-paths to the front of PATH instead of allowing modifications of PATH after +activation to take precedence. + +For example, if you have the following in your `.mise.toml`: + +```toml +[tools] +node = '20' +python = '3.12' +``` + +But you also have this in your `~/.zshrc`: + +```sh +eval "$(mise activate zsh)" +PATH="/some/other/python:$PATH" +``` + +What will happen is `/some/other/python` will be used instead of the python installed by mise. This +means +you typically want to put `mise activate` at the end of your shell config so nothing overrides it. + +If you want to always use the mise versions of tools despite what is in your shell config, set this +to `true`. +In that case, using this example again, `/some/other/python` will be after mise's python in PATH. + +### `asdf_compat` + +* Type: `bool` +* Env: `MISE_ASDF_COMPAT` +* Default: `false` + +Only output `.tool-versions` files in `mise local|global` which will be usable by asdf. +This disables mise functionality that would otherwise make these files incompatible with asdf such +as non-pinned versions. + +This will also change the default global tool config to be `~/.tool-versions` instead +of `~/.config/mise/config.toml`. + +### `disable_tools` + +* Type: `string[]` (comma-delimited) +* Env: `MISE_DISABLE_TOOLS` +* Default: `[]` + +Disables the specified tools. Separate with `,`. Generally used for core plugins but works with any +tool. + +### `status.missing_tools` + +* Type: `enum` +* Env: `MISE_STATUS_MISSING_TOOLS` +* Default: `if_other_versions_installed` + +| Choice | Description | +|-----------------------------------------|----------------------------------------------------------------------------| +| `if_other_versions_installed` [default] | Show the warning only when the tool has at least 1 other version installed | +| `always` | Always show the warning | +| `never` | Never show the warning | + +Show a warning if tools are not installed when entering a directory with a `.mise.toml` file. + +::: tip +Disable tools with [`disable_tools`](#disable_tools). +::: + +### `status.show_env` + +* Type: `bool` +* Env: `MISE_STATUS_SHOW_ENV` +* Default: `false` + +Show configured env vars when entering a directory with a `.mise.toml` file. + +### `status.show_tools` + +* Type: `bool` +* Env: `MISE_STATUS_SHOW_TOOLS` +* Default: `false` + +Show active tools when entering a directory with a `.mise.toml` file. + +## Environment variables + +mise can also be configured via environment variables. The following options are available: + +### `MISE_DATA_DIR` + +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. + +### `MISE_CACHE_DIR` + +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. + +### `MISE_TMP_DIR` + +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. + +### `MISE_SYSTEM_DIR` + +Default: `/etc/mise` + +This is the directory where mise stores system-wide configuration. + +### `MISE_GLOBAL_CONFIG_FILE` + +Default: `$MISE_CONFIG_DIR/config.toml` (Usually ~/.config/mise/config.toml) + +This is the path to the config file. + +### `MISE_DEFAULT_TOOL_VERSIONS_FILENAME` + +Set to something other than ".tool-versions" to have mise look for `.tool-versions` files but with +a different name. + +### `MISE_DEFAULT_CONFIG_FILENAME` + +Set to something other than `.mise.toml` to have mise look for `.mise.toml` config files with a +different name. + +### `MISE_ENV` + +Enables environment-specific config files such as `.mise.development.toml`. +Use this for different env vars or different tool versions in +development/staging/production environments. See +[Profiles](/profiles) for more on how +to use this feature. + +### `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. + +### `MISE_USE_VERSIONS_HOST` + +Default: `true` + +Set to "false" to disable using [mise-versions](https://mise-versions.jdx.dev) as +a quick way for mise to query for new versions. This host regularly grabs all the +latest versions of core and community plugins. It's faster than running a plugin's +`list-all` command and gets around GitHub rate limiting problems when using it. + +See [FAQ](/faq#new-version-of-a-tool-is-not-available) for more information. + +### `MISE_${PLUGIN}_VERSION` + +Set the version for a runtime. For example, `MISE_NODE_VERSION=20` will use regardless +of what is set in `.tool-versions`/`.mise.toml`. + +### `MISE_LEGACY_VERSION_FILE=1` + +Plugins can read the versions files used by other version managers (if enabled by the plugin) +for example, `.nvmrc` in the case of node's nvm. See [legacy version files](#legacy-version-files) +for more +information. + +Set to "0" to disable legacy version file parsing. + +### `MISE_LEGACY_VERSION_FILE_DISABLE_TOOLS=node,python` + +Disable legacy version file parsing for specific tools. Separate with `,`. + +### `MISE_USE_TOML=0` + +Set to `1` to default to using `.mise.toml` in `mise local` instead of `.tool-versions` for +configuration. + +For now this is not used by `mise use` which will only use `.mise.toml` unless `--path` is +specified. + +### `MISE_TRUSTED_CONFIG_PATHS` + +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` + +These change the verbosity of mise. + +You can also use `MISE_DEBUG=1`, `MISE_TRACE=1`, and `MISE_QUIET=1` as well as +`--log-level=trace|debug|info|warn|error`. + +### `MISE_LOG_FILE=~/mise.log` + +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. + +### `MISE_ALWAYS_KEEP_DOWNLOAD=1` + +Set to "1" to always keep the downloaded archive. By default it is deleted after install. + +### `MISE_ALWAYS_KEEP_INSTALL=1` + +Set to "1" to always keep the install directory. By default it is deleted on failure. + +### `MISE_VERBOSE=1` + +This shows the installation output during `mise install` and `mise plugin install`. +This should likely be merged so it behaves the same as `MISE_DEBUG=1` and we don't have +2 configuration for the same thing, but for now it is its own config. + +Equivalent to `MISE_LOG_LEVEL=debug`. + +### `MISE_QUIET=1` + +Equivalent to `MISE_LOG_LEVEL=warn`. + +### `MISE_PARANOID=0` + +Enables extra-secure behavior. See [Paranoid](/paranoid). + +### `MISE_HTTP_TIMEOUT` + +Set the timeout for http requests in seconds. The default is `30`. + +### `MISE_JOBS=1` + +Set the number plugins or runtimes to install in parallel. The default is `4`. + +### `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. + +Sets `MISE_JOBS=1` because only 1 plugin script can be executed at a time. + +### `MISE_SHORTHANDS_FILE=~/.config/mise/shorthands.toml` + +Use a custom file for the shorthand aliases. This is useful if you want to share plugins within +an organization. + +Shorthands make it so when a user runs something like `mise install elixir` mise will +automatically install the [asdf-elixir](https://github.com/asdf-vm/asdf-elixir) plugin. By +default, it uses the shorthands in +[`src/default_shorthands.rs`](https://github.com/jdx/mise/blob/main/src/default_shorthands.rs). + +The file should be in this toml format: + +```toml +elixir = "https://github.com/my-org/mise-elixir.git" +node = "https://github.com/my-org/mise-node.git" +``` + +### `MISE_DISABLE_DEFAULT_SHORTHANDS=1` + +Disables the shorthand aliases for installing plugins. You will have to specify full URLs when +installing plugins, e.g.: `mise plugin install node https://github.com/asdf-vm/asdf-node.git` + +### `MISE_YES=1` + +This will automatically answer yes or no to prompts. This is useful for scripting. + +### `MISE_NOT_FOUND_AUTO_INSTALL=true` + +Set to false to disable the "command not found" handler to autoinstall missing tool versions. +Disable this +if experiencing strange behavior in your shell when a command is not found—but please submit a +ticket to +help diagnose problems. + +### `MISE_TASK_OUTPUT=prefix` + +This controls the output of `mise run`. It can be one of: + +- `prefix` - (default if jobs > 1) print by line with the prefix of the task name +- `interleave` - (default if jobs == 1) display stdout/stderr as it comes in + +### `MISE_EXPERIMENTAL=1` + +Enables experimental features. I generally will publish new features under +this config which needs to be enabled to use them. While a feature is marked +as "experimental" its behavior may change or even disappear in any release. + +The idea is experimental features can be iterated on this way so we can get +the behavior right, but once that label goes away you shouldn't expect things +to change without a proper deprecation—and even then it's unlikely. + +Also, I very often will use experimental as a beta flag as well. New +functionality that I want to test with a smaller subset of users I will often +push out under experimental mode even if it's not related to an experimental +feature. + +If you'd like to help me out, consider enabling it even if you don't have +a particular feature you'd like to try. Also, if something isn't working +right, try disabling it if you can. + +### `MISE_ALL_COMPILE=1` + +Default: false unless running NixOS or Alpine (let me know if others should be added) + +Do not use precompiled binaries for all languages. Useful if running on a Linux distribution +like Alpine that does not use glibc and therefore likely won't be able to run precompiled binaries. + +Note that this needs to be setup for each language. File a ticket if you notice a language that is +not +working with this config. + +### `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. + +Defaults to enabled, set to "0" to disable. diff --git a/docs/contact.md b/docs/contact.md new file mode 100644 index 0000000000..e7b1815e7e --- /dev/null +++ b/docs/contact.md @@ -0,0 +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. + +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/continuous-integration.md b/docs/continuous-integration.md new file mode 100644 index 0000000000..62b245a208 --- /dev/null +++ b/docs/continuous-integration.md @@ -0,0 +1,72 @@ +# Continuous integration + +You can use Mise in continuous integration environments to provision the environment with the tools the project needs. +We recommend that your project pins the tools to a specific version to ensure the environment is reproducible. + +## 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: + +```yaml +script: | + curl https://mise.run | sh + mise install +``` + +To ensure you run the version of the tools installed by Mise, make sure you run them through the `mise x` command: + +```yaml +script: | + mise x npm -- test +``` + +Alternatively, you can add the [shims](/dev-tools/shims.md) directory to your `PATH`, if the CI provider allows it. + +## 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: + +```yaml +name: test +on: + pull_request: + branches: + - main + push: + branches: + - main +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: jdx/mise-action@v2 + with: + version: 2023.12.0 # [default: latest] mise version to install + install: true # [default: true] run `mise install` + cache: true # [default: true] cache mise using GitHub's cache + # automatically write this .tool-versions file + experimental: true # [default: false] enable experimental features + tool_versions: | + shellcheck 0.9.0 + # or, if you prefer .mise.toml format: + mise_toml: | + [tools] + shellcheck = "0.9.0" + - run: shellcheck scripts/*.sh +``` + +## 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: + +```bash +#!/bin/sh +curl https://mise.run | sh +export PATH="$HOME/.local/bin:$PATH" + +mise install # Installs the tools in .mise.toml +eval "$(mise activate bash --shims)" # Adds the activated tools to $PATH + +swiftlint {args} +``` diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000000..2ca3da2b28 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,174 @@ +# 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. + +## Dev Container + +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: + +```sh +mise run docker:cargo build +mise run docker:cargo test +mise run docker:mise --help # run `mise --help` in the dev container +mise run docker:mise run test:e2e # run the e2e tests inside of the docker container +mise run docker:e2e # shortcut for `mise run docker:mise run test:e2e` +``` + +## 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. + +To run locally you will need to first disable mise if you are using it. + +:::code-group + +```sh [dev container] +mise run docker:cargo test +``` + +```sh [local] +cargo test +``` + +::: + +### E2E Tests + +Like unit tests, the e2e tests should be run either in the dev container (recommended) or with mise disabled locally. + +:::code-group + +```sh [dev container] +mise run docker:e2e +``` + +```sh [local] +mise run test:e2e +``` + +::: + +Slow tests do not run by default or on PRs. They can be manually enabled with `TEST_ALL=1`. + +## 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. + +## Tasks + +Mise uses mise itself to run tasks. See available tasks with `mise tasks`: + +```sh +~/src/mise ❯ mise tasks +build ~/src/mise/.mise.toml +clean ~/src/mise/.mise.toml +docker:cargo run cargo inside of development docker … ~/src/mise/.mise.toml +docker:e2e run e2e tests inside of development doc… ~/src/mise/.mise.toml +docker:image build docker image from Dockerfile ~/src/mise/.mise.toml +docker:mise run mise inside of development docker c… ~/src/mise/.mise.toml +format ~/src/mise/.mise.toml +lint ~/src/mise/.mise/config.toml +lint:fix ~/src/mise/.mise.toml +release ~/src/mise/.mise.toml +render ~/src/mise/.mise.toml +render:completions ~/src/mise/.mise.toml +render:help ~/src/mise/.mise.toml +render:mangen ~/src/mise/.mise.toml +signal-test ~/src/mise/.mise.toml +snapshots Update test snapshots ~/src/mise/.mise.toml +test ~/src/mise/.mise.toml +test:e2e ~/src/mise/.mise.toml +``` + +## 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. + +## 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`. + +## 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`: + +```sh +#!/bin/sh +exec cargo run -q --all-features --manifest-path ~/src/mise/Cargo.toml -- "$@" +``` + +::: note +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. + +```sh +@mise --help +@mise run docker:e2e +eval "$(@mise activate zsh)" +@mise activate fish | source +``` + +## Releasing + +Run `mise run release -x [minor|patch]`. (minor if it is the first release in a month) + +## Linting + +- Lint codebase: `mise run lint` +- Lint and fix codebase: `mise run lint:fix` + +## Generating readme and shell completion files + +```sh +mise run render +``` + +## Testing packaging + +This is only necessary to test if actually changing the packaging setup. + +### Ubuntu (apt) + +This is for arm64, but you can change the arch to amd64 if you want. + +```sh +docker run -ti --rm ubuntu +apt update -y +apt install -y gpg sudo wget curl +sudo install -dm 755 /etc/apt/keyrings +wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null +echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list +apt update +apt install -y mise +mise -V +``` + +### Amazon Linux 2 (yum) + +```sh +docker run -ti --rm amazonlinux +yum install -y yum-utils +yum-config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo +yum install -y mise +mise -v +``` + +### Fedora (dnf) + +```sh +docker run -ti --rm fedora +dnf install -y dnf-plugins-core +dnf config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo +dnf install -y mise +mise -v +``` diff --git a/docs/demo.md b/docs/demo.md new file mode 100644 index 0000000000..e1b1ba4d5b --- /dev/null +++ b/docs/demo.md @@ -0,0 +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. + +[![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/deno.md b/docs/deno.md deleted file mode 100644 index 1ece4928b3..0000000000 --- a/docs/deno.md +++ /dev/null @@ -1 +0,0 @@ -Moved to [mise.jdx.dev/lang/deno.html](https://mise.jdx.dev/lang/deno.html). diff --git a/docs/dev-tools/aliases.md b/docs/dev-tools/aliases.md new file mode 100644 index 0000000000..da291ca261 --- /dev/null +++ b/docs/dev-tools/aliases.md @@ -0,0 +1,28 @@ +# Aliases + +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 `.tool-versions`/`.mise.toml`. + +User aliases can be created by adding an `alias.` section to `~/.config/mise/config.toml`: + +```toml +[alias.node] +my_custom_20 = '20' +``` + +Plugins can also provide aliases via a `bin/list-aliases` script. Here is an example showing node.js +versions: + +```bash +#!/usr/bin/env bash + +echo "lts-hydrogen 18" +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. +::: diff --git a/docs/dev-tools/backends/asdf.md b/docs/dev-tools/backends/asdf.md new file mode 100644 index 0000000000..0d4f62295f --- /dev/null +++ b/docs/dev-tools/backends/asdf.md @@ -0,0 +1,22 @@ +# asdf Backend + +asdf is the original backend for mise. It's the default if no backend is specified, +e.g.: `mise i ripgrep` will use [asdf](https://gitlab.com/wt0f/asdf-ripgrep) but `mise i cargo:ripgrep` +will use the [cargo](./cargo) backend. You can explicitly specify the asdf backend with `mise i asdf:ripgrep`. +If you wish. + +There are [hundreds of plugins](https://github.com/mise-plugins/registry) available in the +[mise registry](https://github.com/mise-plugins) and you can also install plugins from git +repos or local directories. + +::: warning +Take care using plugins as well as anything else you get from the internet. CLIs are +unfortunately capable of doing a lot of damage to your system if a bad actor manages to +get into your system through a plugin or other tool. +::: + +## Writing asdf plugins for mise + +See the asdf documentation for more information on [writing plugins](https://asdf-vm.com/plugins/create.html). + +_TODO: document special features only available in mise._ diff --git a/docs/dev-tools/backends/cargo.md b/docs/dev-tools/backends/cargo.md new file mode 100644 index 0000000000..ea2f896559 --- /dev/null +++ b/docs/dev-tools/backends/cargo.md @@ -0,0 +1,61 @@ +# Cargo Backend + +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 of the mise repository at [`./src/forge/cargo.rs`](https://github.com/jdx/mise/blob/main/src/forge/cargo.rs). + +## Dependencies + +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 +``` + +Or you can install it via mise: + +```sh +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: + +```sh +$ mise use -g cargo:eza +$ eza --version +eza - A modern, maintained replacement for ls +v0.17.1 [+git] +https://github.com/eza-community/eza +``` + +The version will be set in `~/.config/mise/config.toml` with the following format: + +```toml +[tools] +"cargo:eza" = "latest" +``` + +## Configuration + +Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable listed. + +### `cargo_binstall` + +* Type: `bool` +* Env: `MISE_CARGO_BINSTALL` +* Default: `true` + +If true, mise will use `cargo binstall` instead of `cargo install` if +[`cargo-binstall`](https://crates.io/crates/cargo-binstall) is installed and on PATH. +This makes installing CLIs with cargo _much_ faster by downloading precompiled binaries. + +You can install it with mise: + +```sh +mise use -g cargo-binstall +``` diff --git a/docs/dev-tools/backends/go.md b/docs/dev-tools/backends/go.md new file mode 100644 index 0000000000..e6338d5662 --- /dev/null +++ b/docs/dev-tools/backends/go.md @@ -0,0 +1,30 @@ +# 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. + +The code for this is inside of the mise repository at [`./src/forge/go.rs`](https://github.com/jdx/mise/blob/main/src/forge/go.rs). + +## Dependencies + +This relies on having `go` installed. Which you can install via mise: + +```sh +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. +::: + +## Usage + +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 +$ hivemind --help +Hivemind version 1.1.0 +``` diff --git a/docs/dev-tools/backends/index.md b/docs/dev-tools/backends/index.md new file mode 100644 index 0000000000..cc649fd7c5 --- /dev/null +++ b/docs/dev-tools/backends/index.md @@ -0,0 +1,16 @@ +# Backends + +In addition to asdf plugins, you can also directly install CLIs with some package managers. + +* [asdf](/dev-tools/backends/asdf) +* [Cargo](/dev-tools/backends/cargo) +* [Go](/dev-tools/backends/go) +* [NPM](/dev-tools/backends/npm) +* [Pipx](/dev-tools/backends/pipx) +* [Ubi](/dev-tools/backends/ubi) +* [More coming soon!](https://github.com/jdx/mise/discussions/1250) + +::: tip +If you'd like to contribute a new backend to mise, they're not difficult to write. +See [`./src/forge/`](https://github.com/jdx/mise/tree/main/src/forge) for examples. +::: diff --git a/docs/dev-tools/backends/npm.md b/docs/dev-tools/backends/npm.md new file mode 100644 index 0000000000..acded46dff --- /dev/null +++ b/docs/dev-tools/backends/npm.md @@ -0,0 +1,33 @@ +# npm Backend + +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/forge/npm.rs`](https://github.com/jdx/mise/blob/main/src/forge/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: + +```sh +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: + +```sh +$ mise use -g npm:prettier +$ prettier --version +3.1.0 +``` + +The version will be set in `~/.config/mise/config.toml` with the following format: + +```toml +[tools] +"npm:prettier" = "latest" +``` diff --git a/docs/dev-tools/backends/pipx.md b/docs/dev-tools/backends/pipx.md new file mode 100644 index 0000000000..6e0c7a5d36 --- /dev/null +++ b/docs/dev-tools/backends/pipx.md @@ -0,0 +1,54 @@ +# pipx Backend + +You may install python packages directly from: + +- PyPI +- Git +- Github +- Http + +The code for this is inside of the mise repository at [`./src/forge/pipx.rs`](https://github.com/jdx/mise/blob/main/src/forge/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: + +```sh +mise use -g python +pip install --user pipx +``` + +Other installation instructions can be found [here](https://pipx.pypa.io/latest/installation/) + +## Usage + +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 +$ black --version +black, 24.3.0 +``` + +The version will be set in `~/.config/mise/config.toml` with the following format: + +```toml +[tools] +"pipx:psf/black" = "latest" +``` + +### Supported Pipx Syntax + +| Description | Usage | +| ------------------------------------- | ------------------------------------------------------ | +| PyPI shorthand latest version | `pipx:black` | +| PyPI shorthand for specific version | `pipx:black@24.3.0` | +| Github shorthand for latest version | `pipx:psf/black` | +| Github shorthand for specific version | `pipx:psf/black@24.3.0` | +| Git syntax for latest version | `pipx:git+https://github.com/psf/black` | +| Git syntax for a branch | `pipx:git+https://github.com/psf/black.git@main` | +| Https with zipfile | `pipx:https://github.com/psf/black/archive/18.9b0.zip` | + +Other syntax may work but is unsupported and untested. diff --git a/docs/dev-tools/backends/ubi.md b/docs/dev-tools/backends/ubi.md new file mode 100644 index 0000000000..581e458d4d --- /dev/null +++ b/docs/dev-tools/backends/ubi.md @@ -0,0 +1,42 @@ +# Ubi Backend + +You may install Github Releases and URL packages directly using [ubi](https://github.com/houseabsolute/ubi) backend. + +The code for this is inside of the mise repository at [`./src/forge/ubi.rs`](https://github.com/jdx/mise/blob/main/src/forge/ubi.rs). + +## Dependencies + +This relies on having `ubi` installed. You can install it with or without mise. +Here is how to install `ubi` with mise: + +```sh +mise use -g cargo:ubi +``` + +## Usage + +The following installs the latest version of goreleaser +and sets it as the active version on PATH: + +```sh +$ mise use -g ubi:goreleaser/goreleaser +$ goreleaser --version +1.25.1 +``` + +The version will be set in `~/.config/mise/config.toml` with the following format: + +```toml +[tools] +"ubi:goreleaser/goreleaser" = "latest" +``` + +### Supported Ubi Syntax + +| Description | Usage | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| 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` | + +Other syntax may work but is unsupported and untested. diff --git a/docs/dev-tools/comparison-to-asdf.md b/docs/dev-tools/comparison-to-asdf.md new file mode 100644 index 0000000000..d2bc68bfa3 --- /dev/null +++ b/docs/dev-tools/comparison-to-asdf.md @@ -0,0 +1,106 @@ +# 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 uses asdf plugins. 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. + +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.html) and [tasks](/tasks/) which +are major portions of mise that have no asdf equivalent. +::: + +## 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. + +asdf requires several steps to install a new runtime if the plugin isn't installed, e.g.: + +```sh +asdf plugin add node +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: + +```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: + +```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. + +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. + +## 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.: + +```sh +mise install node 20.0.0 +mise local node 20.0.0 +``` + +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: + +```sh +mise use -g cargo:ripgrep@14 +mise use -g npm:prettier@3 +``` diff --git a/docs/dev-tools/index.md b/docs/dev-tools/index.md new file mode 100644 index 0000000000..73de097bf3 --- /dev/null +++ b/docs/dev-tools/index.md @@ -0,0 +1,122 @@ +# 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](/plugins)._ + +::: 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 for managing programming language and tool versions. For example, use this to install +a particular version of Node.js and ruby for a project. Using `mise activate`, you can have your +shell automatically switch to the correct node and ruby versions when you `cd` into the project's +directory. Other projects on your machine can use a different set of versions. + +mise is inspired by [asdf](https://asdf-vm.com) and uses asdf's vast [plugin ecosystem](https://github.com/rtx-plugins/registry) +under the hood. However, it is _much_ faster than asdf and has a more friendly user experience. +For more on how mise compares to asdf, [see below](./comparison-to-asdf). + +mise can be configured in many ways. The most typical is by `.mise.toml`, but it's also compatible +with asdf `.tool-versions` files. It can also use idiomatic version files like `.node-version` and +`.ruby-version`. See [Configuration](/configuration) for more. + +* Like [direnv](https://github.com/direnv/direnv) it manages [environment variables](/configuration#env---arbitrary-environment-variables) for different project directories. +* Like [make](https://www.gnu.org/software/make/manual/make.html) it manages [tasks](/tasks/) used to build and test projects. + +## 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 `.tool-versions`/`.mise.toml` file, mise will automatically set the +appropriate tool versions in `PATH`. + +::: info +mise does not modify "cd". It actually runs every time 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 `.tool-versions`/`.mise.toml` files haven't been modified. + +Unlike asdf which uses shim files to dynamically locate runtimes when they're called, mise modifies +`PATH` ahead of time so the runtimes are called directly. This is not only faster since it avoids +any overhead, but it also makes it so commands like `which node` work as expected. This also +means there isn't any need to run `asdf reshim` after installing new runtime binaries. + +You should note that mise does not directly install these tools. +Instead, it leverages plugins to install runtimes. +See [plugins](/plugins) below. + +## Common commands + +Here are some of the most important commands when it comes to working with dev tools. + +### `mise use` + +For some users, `mise use` might be the only command you need to learn. It will do the following: + +- Install the tool's plugin if needed +- Install the specified version +- Set the version as active (it's in PATH) + +`mise use node@20` will install the latest version of node-20 and create/update the .tool-versions/.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@20` will do the same but update the global config (~/.config/mise/config.toml) so +unless there is a config file in the local directory hierarchy, node-20 will be the default version for +the user. + +### `mise 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 `.tool-versions` or `.mise-toml` 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. +::: + +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 .tool-versions/.mise.toml +* `mise install` - install all plugins and tools + +### `mise local|global` + +`mise local` and `mise global` are command which only modify the `.tool-versions` or `.mise.toml` files. +These are hidden from the CLI help and remain for asdf-compatibility. The recommended approach is +to use `mise use` instead because that will do the same thing but also install the tool if it does +not already exists. + +### `mise exec`|`mise x` + +`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 `.tool-versions`/`.mise-toml` 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 +$ mise x -- node -v +20.x.x +``` + +::: tip +If you use this a lot, an alias can be helpful: + +```sh +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. diff --git a/docs/dev-tools/shims.md b/docs/dev-tools/shims.md new file mode 100644 index 0000000000..843bee69a4 --- /dev/null +++ b/docs/dev-tools/shims.md @@ -0,0 +1,194 @@ +# 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. +::: + +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`. + +```sh +$ mise use -g node@20 +$ npm install -g prettier@3.1.0 +$ mise reshim # may be required if new shims need to be created after installing packages +$ ~/.local/share/mise/shims/node -v +v20.0.0 +$ ~/.local/share/mise/shims/prettier -v +3.1.0 +``` + +::: 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. + +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. +::: + +## Shims vs PATH + +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: + +```sh +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. + +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. +::: + +### `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: + +```sh +$ which node +/Users/jdx/.mise/installs/node/20/bin/node +``` + +### 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`: + +```sh +$ mise set NODE_ENV=production +$ echo $NODE_ENV +production +``` + +But this will work in either: + +```sh +$ mise set NODE_ENV=production +$ 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: + +```sh +$ mise set NODE_ENV=production +$ mise x -- bash -c "echo \$NODE_ENV" +production +$ 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. +::: + +## 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. + +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: + +::: code-group + +```sh [hook-env] +eval "$(mise activate zsh)" +eval "$(mise hook-env -s zsh)" +node some_script.js +``` + +```sh [shims] +eval "$(mise activate zsh --shims)" # should be first +eval "$(mise activate zsh)" +node some_script.js +``` + +::: + +The `hook-env` option is the one I would go with. It's a bit cleaner since you won't have the shims +inside your PATH at all. If you do go with shims, it will need to be first so they get overridden. + +## 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. + +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. + +If you are calling a shim from within a bash script like this: + +```sh +for i in {1..500}; do + node script.js +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. + +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`. + +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`. + +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. diff --git a/docs/directories.md b/docs/directories.md new file mode 100644 index 0000000000..24db50ff06 --- /dev/null +++ b/docs/directories.md @@ -0,0 +1,83 @@ +# Directory Structure + +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. +::: + +## `~/.config/mise` + +* Override: `$MISE_CONFIG_DIR` +* Default: `${XDG_CONFIG_HOME:-$HOME/.config}/mise` + +This directory stores the global configuration file `~/.config/mise/config.toml`. This is intended to go into your +dotfiles repo to share across machines. + +## `~/.cache/mise` + +* 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. + +## `~/.local/state/mise` + +* Override: `$MISE_STATE_DIR` +* Default: `${XDG_STATE_HOME:-$HOME/.local/state}/mise` + +Used for storing state local to the machine such as which config files are trusted. These should not be shared across +machines. + +## `~/.local/share/mise` + +* 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 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. + +### `~/.local/share/mise/plugins` + +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 +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 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 +20 -> ./20.15.0 +20.15 -> ./20.15.0 +lts -> ./20.15.0 +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. diff --git a/docs/direnv.md b/docs/direnv.md new file mode 100644 index 0000000000..bb71a12f63 --- /dev/null +++ b/docs/direnv.md @@ -0,0 +1,91 @@ +# 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. + +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 +Update 2024-01-21: after `use mise` has been out for a while, the general impression I have is that +while it technically functions fine, +not many people use it because the DX is notably worse than either switching to mise entirely +or using `mise activate` alongside direnv. + +The project direction of mise has changed since this was written and the new direction is for it +to be capable of replacing direnv completely for any use-case. This likely won't end up as a drop-in +replacement for direnv like with asdf, but solving the same problems in different ways. +See [environments](/environments.html) +for more details. + +I have had virtually no reports of problems with `use mise` in the year it has been out. +This could be because virtually is using it, or it has been surprisingly stable. I genuinely +don't know which. If you try it or use it regularly let me know. + +While I have no immediate plans or reasons to do this now, I could see this functionality being +the target of a future deprecation. Not because it's a maintenance burden, but because it just +hasn't +seemed like a particularly useful solution and it may help focus mise on the functionality that does +work for users. +::: + +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. + +To do this, first use `mise` to build a `use_mise` function that you can use in `.envrc` files: + +```sh +mise direnv activate > ~/.config/direnv/lib/use_mise.sh +``` + +Now in your `.envrc` file add the following: + +```sh +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`. + +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. + +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`. diff --git a/docs/environments.md b/docs/environments.md new file mode 100644 index 0000000000..aac217f9de --- /dev/null +++ b/docs/environments.md @@ -0,0 +1,129 @@ +# Environments + +Use mise to specify environment variables used for different projects. Create a `.mise.toml` file +in the root of your project directory: + +```toml +[env] +NODE_ENV = 'production' +``` + +To clear an env var, set it to `false`: + +```toml +[env] +NODE_ENV = false # unset a previously set NODE_ENV +``` + +You can also use the CLI to get/set env vars: + +```sh +$ mise set NODE_ENV=development +$ mise set NODE_ENV +development +$ mise set +key value source +NODE_ENV development .mise.toml +$ mise unset NODE_ENV +``` + +## `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._.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: + +```toml +[env] +_.file = '.env' +``` + +_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. + +### `env._.path` + +`PATH` is treated specially, it needs to be defined as a string/array in `mise.path`: + +```toml +[env] +_.path = [ + # adds an absolute path + "~/.local/share/bin", + # adds a path relative to the .mise.toml, not PWD + "./node_modules/.bin", +] +``` + +### `env._.source` + +Source an external bash script and pull exported environment variables out of it: + +```toml +[env] +_.source = "./script.sh" +``` + +::: 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. +::: + +## 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: + +```toml +[env] +_.source = "./script_1.sh" +_.source = "./script_2.sh" # invalid // [!code error] +``` + +For this use-case, you can optionally make `[env]` an array-of-tables instead by using `[[env]]` instead: + +```toml +[[env]] +_.source = "./script_1.sh" +[[env]] +_.source = "./script_2.sh" +``` + +It works identically but you can have multiple tables. + +## Templates + +Environment variable values can be templates, see [Templates](/templates) for details. + +```toml +[env] +LD_LIBRARY_PATH = "/some/path:{{env.LD_LIBRARY_PATH}}" +``` + +## Using env vars in other env vars + +You can use the value of an environment variable in later env vars: + +```toml +[env] +MY_PROJ_LIB = "{{config_root}}/lib" +LD_LIBRARY_PATH = "/some/path:{{env.MY_PROJ_LIB}}" +``` + +Of course the ordering matters when doing this. diff --git a/docs/errors.md b/docs/errors.md new file mode 100644 index 0000000000..f96b8b9a04 --- /dev/null +++ b/docs/errors.md @@ -0,0 +1,3 @@ +# Errors + +TODO diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000000..5b35c537fc --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,256 @@ +# FAQs + +## I don't want to put a `.tool-versions` file into my project since git shows it as an untracked file + +You can make git ignore these files in 3 different ways: + +- Adding `.tool-versions` to project's `.gitignore` file. This has the downside that you need to + commit the change to the ignore file. +- Adding `.tool-versions` to project's `.git/info/exclude`. This file is local to your project so + there is no need to commit it. +- Adding `.tool-versions` to global gitignore (`core.excludesFile`). This will cause git to + ignore `.tool-versions` files in all projects. You can explicitly add one to a project if needed + with `git add --force .tool-versions`. + +## 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. + +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 `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. + +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/#mise-exec-options-tool-version-command). +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)"`. + +## `mise activate` doesn't work in `~/.profile`, `~/.bash_profile`, `~/.zprofile` + +`mise activate` should only be used in `rc` files. These are the interactive ones used when +a real user is using the terminal. (As opposed to being executed by an IDE or something). The prompt +isn't displayed in non-interactive environments so PATH won't be modified. + +For non-interactive setups, consider using shims instead which will route calls to the correct +directory by looking at `PWD` every time they're executed. You can also call `mise exec` instead of +expecting things to be directly on PATH. You can also run `mise env` in a non-interactive shell, +however that +will only setup the global tools. It won't modify the environment variables when entering into a +different project. + +Also see the [shebang](/tips-and-tricks#shebang) example for a way to make scripts call mise to get +the runtime. +That is another way to use mise without activation. + +## mise is failing or not working right + +First try setting `MISE_DEBUG=1` or `MISE_TRACE=1` and see if that gives you more information. +You can also set `MISE_LOG_FILE_LEVEL=debug MISE_LOG_FILE=/path/to/logfile` to write logs to a file. + +If something is happening with the activate hook, you can try disabling it and +calling `eval "$(mise hook-env)"` manually. +It can also be helpful to use `mise env` which will just output environment variables that would be +set. +Also consider using [shims](/dev-tools/shims.md) which can be more compatible. + +If runtime installation isn't working right, try using the `--raw` flag which will install things in +series and connect stdin/stdout/stderr directly to the terminal. If a plugin is trying to interact +with you for some reason this will make it work. + +Of course check the version of mise with `mise --version` and make sure it is the latest. +Use `mise self-update` +to update it. `mise cache clean` can be used to wipe the internal cache and `mise implode` can be +used +to remove everything except config. + +Before submitting a ticket, it's a good idea to test what you were doing with asdf. That way we can +rule +out if the issue is with mise or if it's with a particular plugin. For example, +if `mise install python@latest` +doesn't work, try running `asdf install python latest` to see if it's an issue with asdf-python. + +Lastly, there is `mise doctor` which will show diagnostic information and any warnings about issues +detected with your setup. If you submit a bug report, please include the output of `mise doctor`. + +## New version of a tool is not available + +There are 2 places that versions are cached so a brand new release might not appear right away. + +The first is that the mise CLI caches versions for 24 hours. This can be cleared +with `mise cache clear`. + +The second uses the mise-versions.jdx.dev host as a centralized +place to list all of the versions of most plugins. This is intended to speed up mise and also +get around GitHub rate limits when querying for new versions. Check that repo for your plugin to +see if it has an updated version. This service can be disabled by +setting `MISE_USE_VERSIONS_HOST=0`. + +## Windows support? + +This is something we'd like to add! + +It's not a near-term goal and it would require plugin modifications, but it should be feasible. + +## How do I use mise with http proxies? + +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. + +## 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/rtx-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/src/default_shorthands.rs). + +## 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: + +```sh +$ ls -l ~/.local/share/mise/installs/node/20 +[...] /home/jdx/.local/share/mise/installs/node/20 -> node-v20.0.0-linux-x64 +``` + +There are some exceptions to this, such as the following: + +- `mise install node@20` +- `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. + +## How do I migrate from asdf? + +First, just install mise with `mise activate` like in the getting started guide and remove asdf from +your +shell rc file. + +Then you can just run `mise install` in a directory with an asdf `.tool-versions` file and it will +install the runtimes. You could attempt to avoid this by copying the internal directory from asdf +over +to mise with `cp -r ~/.asdf ~/.local/share/mise`. That _should_ work because they use the same +structure, +however this isn't officially supported or regularly tested. Alternatively you can +set `MISE_DATA_DIR=~/.asdf` +and see what happens. + +## 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. If it doesn't open a ticket. It may +not be possible to support every command identically, but +we should attempt to make things as consistent as possible. + +This isn't important for usability reasons so much as making it so plugins continue to work that +call asdf commands. + +If you need to switch to/from asdf or work in a project with asdf users, you can set +[`MISE_ASDF_COMPAT=1`](/configuration#mise_asdf_compat1). That prevents +mise from writing `.tool-versions` files that will not be +compatible with asdf. Also consider using `.mise.toml` instead which won't conflict with asdf +setups. + +## mise isn't working when calling from tmux or another shell initialization script + +`mise activate` will not update PATH until the shell prompt is displayed. So if you need to access a +tool provided by mise before the prompt is displayed you can either +[add the shims to your PATH](getting-started.html#2-add-mise-shims-to-path) e.g. + +```bash +export PATH="$HOME/.local/share/mise/shims:$PATH" +python --version # will work after adding shims to PATH +``` + +Or you can manually call `hook-env`: + +```bash +eval "$(mise activate bash)" +eval "$(mise hook-env)" +python --version # will work only after calling hook-env explicitly +``` + +For more information, see [What does `mise activate` do?](#what-does-mise-activate-do) + +## 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/): + +- `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. +- `CLICOLOR_FORCE != 0`: ANSI colors should be enabled no matter what. + +## 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. + +For more details see [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md). diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000000..2bda2255a3 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,421 @@ +# Getting Started + +Using mise typically involves 3 steps: + +1. Installing the CLI +2. Activating mise or adding its shims to PATH +3. Adding tools to mise + +## Quickstart + +### 1. Install `mise` CLI + +First we need to download the mise CLI. +See [below](#alternate-installation-methods) for alternate installation methods. +This directory is simply a suggestion. +mise can be installed anywhere. + +```sh +$ curl https://mise.run | sh +$ ~/.local/bin/mise --version +mise 2024.x.x +``` + +::: tip +"~/.local/bin" does not need to be in PATH. mise will automatically add its own directory to PATH +when activated. +::: + +### 2a. Activate mise + +`mise activate` is one way to setup mise but alternatively you can +use [shims](dev-tools/shims.md), [direnv](./direnv), or skip +this step entirely. If you skip it, then tools like `npm` and `node` will not be in PATH. You'll +need to prefix +commands with `mise exec` or run tasks with `mise run` in order to use tools managed with mise. + +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. + +::: code-group + +```sh [bash] +echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc +``` + +```sh [zsh] +echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc +``` + +```sh [fish] +echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish +``` + +::: + +### 2b. Alternative: 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). + +::: code-group + +```sh [bash] +# note that bash will read from ~/.profile or ~/.bash_profile if the latter exists +# ergo, you may want to check to see which is defined on your system and only append to the existing file +echo 'export PATH="$HOME/.local/share/mise/shims:$PATH"' >> ~/.bash_profile +``` + +```sh [zsh] +echo 'export PATH="$HOME/.local/share/mise/shims:$PATH"' >> ~/.zprofile +``` + +```sh [fish] +fish_add_path ~/.local/share/mise/shims +``` + +:::tip +You can also run `mise activate --shims` which will do the above for you. +::: + +:::info +mise respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like +to change these locations. +::: + +### 3. Adding tools to mise + +:::info +Of course, if using mise solely for [environment management](/environments) +or [running tasks](/tasks/) +this step is not necessary. +::: + +Install node and set it as the global default: + +```sh +$ mise use --global node@20 +$ node -v +v20.x.x +``` + +If you did not activate mise or add its shims to PATH, then you'll need to run the following: + +```sh +$ mise use --global node@20 +$ mise exec -- node -v +v20.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. +::: + +## Alternate Installation Methods + +### + +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 +``` + +Options: + +- `MISE_DEBUG=1` – enable debug logging +- `MISE_QUIET=1` – disable non-error output +- `MISE_INSTALL_PATH=/some/path` – change the binary path (default: `~/.local/bin/mise`) +- `MISE_VERSION=v2024.5.17` – install a specific version + +If you want to verify the install script hasn't been tampered with: + +```sh +gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 0x7413A06D +curl https://mise.jdx.dev/install.sh.sig | gpg --decrypt > install.sh +# ensure the above is signed with the mise release key +sh ./install.sh +``` + +or if you're allergic to `| sh`: + +::: code-group + +```sh [macos-arm64] +curl https://mise.jdx.dev/mise-latest-macos-arm64 > ~/.local/bin/mise +``` + +```sh [macos-x64] +curl https://mise.jdx.dev/mise-latest-macos-x64 > ~/.local/bin/mise +``` + +```sh [linux-x64] +curl https://mise.jdx.dev/mise-latest-linux-x64 > ~/.local/bin/mise +``` + +```sh [linux-arm64] +curl https://mise.jdx.dev/mise-latest-linux-arm64 > ~/.local/bin/mise +``` + +::: + +It doesn't matter where you put it. So use `~/bin`, `/usr/local/bin`, `~/.local/bin` or whatever. + +Supported os/arch: + +- `macos-x64` +- `macos-arm64` +- `linux-x64` +- `linux-x64-musl` +- `linux-arm64` +- `linux-arm64-musl` +- `linux-armv6` +- `linux-armv6-musl` +- `linux-armv7` +- `linux-armv7-musl` + +If you need something else, compile it with `cargo install mise` (see below). +[Windows isn't currently supported.](https://github.com/jdx/mise/discussions/66) + +### apk + +For Alpine Linux: + +``` +apk add mise +``` + +_mise lives in +the [community repository](https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/community/mise/APKBUILD)._ + +### apt + +For installation on Ubuntu/Debian: + +::: code-group + +```sh [amd64] +apt update -y && apt install -y gpg sudo wget curl +sudo install -dm 755 /etc/apt/keyrings +wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null +echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=amd64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list +sudo apt update +sudo apt install -y mise +``` + +```sh [arm64] +apt update -y && apt install -y gpg sudo wget curl +sudo install -dm 755 /etc/apt/keyrings +wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null +echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list +sudo apt update +sudo apt install -y mise +``` + +::: + +### aur + +For Arch Linux: + +```sh +git clone https://aur.archlinux.org/mise.git +cd mise +makepkg -si +``` + +### Cargo + +Build from source with Cargo: + +```sh +cargo install mise +``` + +Do it faster with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall): + +```sh +cargo install cargo-binstall +cargo binstall mise +``` + +Build from the latest commit in main: + +```sh +cargo install mise --git https://github.com/jdx/mise --branch main +``` + +### dnf + +For Fedora, CentOS, Amazon Linux, RHEL and other dnf-based distributions: + +``` +dnf install -y dnf-plugins-core +dnf config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo +dnf install -y mise +``` + +### Docker + +``` +docker run jdxcode/mise x node@20 -- node -v +``` + +### Homebrew + +```sh +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`. + +```sh +npm install -g @jdxcode/mise +``` + +Use npx if you just want to test it out for a single command without fully installing: + +```sh +npx @jdxcode/mise exec python@3.11 -- python some_script.py +``` + +### GitHub Releases + +Download the latest release from [GitHub](https://github.com/jdx/mise/releases). + +```sh +curl https://github.com/jdx/mise/releases/download/v2024.1.0/mise-v2024.1.0-linux-x64 > /usr/local/bin/mise +chmod +x /usr/local/bin/mise +``` + +### MacPorts + +```sh +sudo port install mise +``` + +### nix + +For the Nix package manager, at release 23.05 or later: + +```sh +nix-env -iA mise +``` + +You can also import the package directly using +`mise-flake.packages.${system}.mise`. It supports all default Nix +systems. + +### yum + +```sh +yum install -y yum-utils +yum-config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo +yum install -y mise +``` + +## Shells + +### Bash + +```sh +echo 'eval "$(mise activate bash)"' >> ~/.bashrc +``` + +### Zsh + +```sh +echo 'eval "$(mise activate zsh)"' >> "${ZDOTDIR-$HOME}/.zshrc" +``` + +### Fish + +```sh +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. + +See [`MISE_FISH_AUTO_ACTIVATE=1`](/configuration#mise_fish_auto_activate1) for more information. +::: + +### Nushell + +Since Nu +does [not support `eval`](https://www.nushell.sh/book/how_nushell_code_gets_run.html#eval-function) +the initialization script is saved in `env.nu`: + +```nushell +' +let mise_path = $nu.default-config-dir | path join scripts mise.nu +^mise activate nu | save $mise_path --force +' | save $nu.env-path --append +"\nuse 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`: + +```nushell +"\n$env.NU_LIB_DIRS ++= ($mise_path | path dirname | to nuon)" | save $nu.env-path --append +``` + +### 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`: + +```python +from pathlib import Path +from xonsh.built_ins import XSH + +ctx = XSH.ctx +mise_init = subprocess.run([Path('~/bin/mise').expanduser(),'activate','xonsh'],capture_output=True,encoding="UTF-8").stdout +XSH.builtins.execx(mise_init,'exec',ctx,filename='mise') +``` + +Or continue to use `rc.xsh`/`.xonshrc`: + +```sh +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) + +### 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. + +## 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. + +Alternatively, manually remove the following directories to fully clean up: + +- `~/.local/share/mise` (can also be `MISE_DATA_DIR` or `XDG_DATA_HOME/mise`) +- `~/.local/state/mise` (can also be `MISE_STATE_DIR` or `XDG_STATE_HOME/mise`) +- `~/.config/mise` (can also be `MISE_CONFIG_DIR` or `XDG_CONFIG_HOME/mise`) +- on Linux: `~/.cache/mise` (can also be `MISE_CACHE_DIR` or `XDG_CACHE_HOME/mise`) +- on macOS: `~/Library/Caches/mise` (can also be `MISE_CACHE_DIR`) diff --git a/docs/go.md b/docs/go.md deleted file mode 100644 index d4e61f552d..0000000000 --- a/docs/go.md +++ /dev/null @@ -1 +0,0 @@ -Moved to [mise.jdx.dev/lang/go.html](https://mise.jdx.dev/lang/go.html). diff --git a/docs/how-i-use-mise.md b/docs/how-i-use-mise.md new file mode 100644 index 0000000000..f5d06e4acb --- /dev/null +++ b/docs/how-i-use-mise.md @@ -0,0 +1,122 @@ +# 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. + +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. + +## My setup + +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. + +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`. + +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 +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. +::: + +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 +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. + +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. + +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. + +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. + +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. + +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` + +I often need to access mise's internals so I do the following: + +```sh +ln -s ~/.mise ~/.config/mise +ln -s ~/.mise ~/.local/share/mise +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. diff --git a/docs/ide-integration.md b/docs/ide-integration.md new file mode 100644 index 0000000000..e07f574770 --- /dev/null +++ b/docs/ide-integration.md @@ -0,0 +1,159 @@ +# IDE Integration + +IDEs work better with 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: + +* macos – `dscl . -read /Users/$USER UserShell` +* linux – `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: + +::: code-group + +```zsh +# ~/.zprofile +eval "$(mise activate zsh --shims)" +``` + +```bash +# ~/.bash_profile or ~/.bash_login or ~/.profile +eval "$(mise activate bash --shims)" +``` + +```fish +# ~/.config/fish/config.fish +if status is-interactive + mise activate fish | source +else + mise activate fish --shims | source +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)"`). + +This won't work for all of mise's functionality. For example, arbitrary env vars in `[env]` will +only be set +if a shim is executed. For this we need tighter integration with the IDE and a custom plugin. If you +feel +ambitious, take a look at existing direnv extensions for your IDE 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 + +```vim +" Prepend mise shims to PATH +let $PATH = $HOME . '/.local/share/mise/shims:' . $PATH +``` + +## Neovim + +```lua +-- Prepend mise shims to PATH +vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH +``` + +## emacs + +- Traditional shims way + +```lisp +;; CLI tools installed by Mise +;; See: https://www.emacswiki.org/emacs/ExecPath +(setenv "PATH" (concat (getenv "PATH") ":/home/user/.local/share/mise/shims")) +(setq exec-path (append exec-path '("/home/user/.local/share/mise/shims"))) +``` + +- Use with package [mise.el](https://github.com/liuyinz/mise.el) + +```lisp +(require 'mise) +(add-hook 'after-init-hook #'global-mise-mode) +``` + +## 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: + +```bash +# -C ensures that Mise loads the configuration from the Mise configuration +# file in the project's root directory. +eval "$($HOME/.local/bin/mise activate -C $SRCROOT bash --shims)" + +swiftlint +``` + +## JetBrains Editors (IntelliJ, RustRover, PyCharm, WebStorm, RubyMine, GoLand, etc) + +Some JetBrains IDEs have direct support for mise, others have support for asdf which can be used by +first symlinking the mise tool directory which is the +same layout as asdf: + +```sh +ln -s ~/.local/share/mise ~/.asdf +``` + +Then they should show up on in Project Settings: + +![project settings](https://github.com/jdx/mise-docs/assets/216188/b34a0e3f-7af8-45c9-85b8-2c72bd1dc226) + +Or in the case of node (possibly other languages), it's under "Languages & Frameworks": + +![languages & frameworks](https://github.com/jdx/mise-docs/assets/216188/9926be1c-ab88-451a-8ace-edf2dac564b5) + +## VSCode + +While modifying `~/.zprofile` is likely the easiest solution, you can also set +the tools in `launch.json`: + +```json +{ + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${file}", + "args": [], + "osx": { + "runtimeExecutable": "mise" + }, + "linux": { + "runtimeExecutable": "mise" + }, + "runtimeArgs": [ + "x", + "--", + "node" + ] + } + ] +} +``` + +## [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). + +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/index.md b/docs/index.md new file mode 100644 index 0000000000..829a48f0ba --- /dev/null +++ b/docs/index.md @@ -0,0 +1,39 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home +title: Home + +hero: + name: mise-en-place + tagline: | + The front-end to your dev env + Pronounced "MEEZ ahn plahs" + actions: + - theme: brand + text: Getting Started + link: /getting-started + - theme: alt + text: About + link: /about + - theme: alt + text: GitHub + link: https://github.com/jdx/mise + - theme: alt + text: Discord + link: https://discord.gg/UBa7pJUN7Z + +features: + - title: Dev Tools + details: mise is a polyglot tool version manager. It replaces tools like asdf, nvm, pyenv, rbenv, etc. + - title: Environments + details: mise allows you to switch sets of env vars in different project directories. It can replace direnv. + - title: Tasks + details: mise is a task runner that can replace make, or npm scripts. +--- + + diff --git a/docs/java.md b/docs/java.md deleted file mode 100644 index abd1974f13..0000000000 --- a/docs/java.md +++ /dev/null @@ -1 +0,0 @@ -Moved to [mise.jdx.dev/lang/java.html](https://mise.jdx.dev/lang/java.html). diff --git a/docs/lang/bun.md b/docs/lang/bun.md new file mode 100644 index 0000000000..d30178b508 --- /dev/null +++ b/docs/lang/bun.md @@ -0,0 +1,18 @@ +# 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). + +## Usage + +The following installs bun and makes it the global default: + +```sh +mise use -g bun@0.7 # install bun 0.7.x +mise use -g bun@latest # install latest bun +``` + +See available versions with `mise ls-remote bun`. diff --git a/docs/lang/deno.md b/docs/lang/deno.md new file mode 100644 index 0000000000..3208f1f60b --- /dev/null +++ b/docs/lang/deno.md @@ -0,0 +1,21 @@ +# 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`. + +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). + +## Usage + +The following installs deno and makes it the global default: + +```sh +mise use -g deno@1 # install deno 1.x +mise use -g deno@latest # install latest deno +``` + +See available versions with `mise ls-remote deno`. diff --git a/docs/lang/erlang.md b/docs/lang/erlang.md new file mode 100644 index 0000000000..6bccd968ed --- /dev/null +++ b/docs/lang/erlang.md @@ -0,0 +1,22 @@ +# 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). + +## Usage + +The following installs erlang and makes it the global default: + +```sh +mise use -g erlang@26 +``` + +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. diff --git a/docs/lang/go.md b/docs/lang/go.md new file mode 100644 index 0000000000..064668dc84 --- /dev/null +++ b/docs/lang/go.md @@ -0,0 +1,101 @@ +# 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`. + +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: + +```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: + +```sh +mise use -g go@prefix:1.20 +``` + +## Configuration + +Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable. + +### `go_default_packages_file` + +* Type: `string` +* Env: `MISE_GO_DEFAULT_PACKAGES_FILE` +* Default: `~/.default-go-packages` + +Packages list to install with `go install` after installing a Go version. + +### `go_download_mirror` + +* Type: `string` +* Env: `MISE_GO_DOWNLOAD_MIRROR` +* Default: `https://dl.google.com/go` + +URL to download go sdk tarballs from. + +### `go_repo` + +* Type: `string` +* Env: `MISE_GO_REPO` +* Default: `https://github.com/golang/go` + +Used to get latest go version from GitHub releases. + +### `go_set_gobin` + +* Type: `bool | null` +* Env: `MISE_GO_SET_GOBIN` +* Default: `null` + +Sets `GOBIN` to `~/.local/share/mise/go/installs/[VERSION]/bin`. This causes CLIs installed via +`go install` to have shims created for it which will have env vars from mise such as GOROOT set. + +If not using shims or not using `go install` with tools that require GOROOT, it can probably be +safely disabled. See the [go backend](https://mise.jdx.dev/dev-tools/backends/) for the preferred +method to install Go CLIs. + +### `go_set_gopath` + +* Type: `bool` +* Env: `MISE_GO_SET_GOPATH` +* Default: `false` + +Sets `GOPATH` to `~/.local/share/mise/go/installs/[VERSION]/packages`. This retains behavior from +asdf and older mise/rtx versions. There is no known reason for this to be enabled but it is available +(for now) just in case anyone relies on it. + +### `go_skip_checksum` + +* Type: `bool` +* Env: `MISE_GO_SKIP_CHECKSUM` +* Default: `false` + +Skips checksum verification of downloaded go tarballs. + +## 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: + +```text +github.com/Dreamacro/clash # allows comments +github.com/jesseduffield/lazygit +``` + +## `.go-version` file support + +mise uses a `.tool-versions` or `.mise.toml` 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 new file mode 100644 index 0000000000..2d2a83ccdf --- /dev/null +++ b/docs/lang/java.md @@ -0,0 +1,76 @@ +# 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`. + +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 java-openjdk-17.x (if some version of openjdk-17.x is +not already installed) and makes it the global default: + +```sh +mise use -g java@openjdk-17 +mise use -g java@17 # alternate shorthands for openjdk-only +``` + +See available versions with `mise ls-remote java`. + +## macOS JAVA_HOME Integration + +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-20). + +```sh +sudo mkdir /Library/Java/JavaVirtualMachines/openjdk-20.jdk +sudo ln -s ~/.local/share/mise/installs/java/openjdk-20/Contents /Library/Java/JavaVirtualMachines/openjdk-20.jdk/Contents +``` + +> Note: Not all distributions of the Java SDK support this integration (e.g liberica). + +## Legacy version files + +The Java core plugin supports the legacy 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). + +In case an unsupported version of java is needed, some manual work is required: + +1. Download the unsupported version to a directory (e.g `~/.sdkman/candidates/java/21.0.1-open`) +2. symlink the new version: + +```sh +ln -s ~/.sdkman/candidates/java/21.0.1-open ~/.local/share/mise/installs/java/21.0.1-open +``` + +3. If on Mac: + +```sh +mkdir ~/.local/share/mise/installs/java/21.0.1-open/Contents +mkdir ~/.local/share/mise/installs/java/21.0.1-open/Contents/MacOS + +ln -s ~/.sdkman/candidates/java/21.0.1-open ~/.local/share/mise/installs/java/21.0.1-open/Contents/Home +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. + +```sh +$ ls -R $MISE_CACHE_DIR/java +21.0.1-open + +mise/java/21.0.1-open: +``` diff --git a/docs/lang/node.md b/docs/lang/node.md new file mode 100644 index 0000000000..a54cb5534c --- /dev/null +++ b/docs/lang/node.md @@ -0,0 +1,59 @@ +# 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` + +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: + +```sh +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. + +## Configuration + +- `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_COMPILE` [bool]: Forces compilation from source instead of preferring pre-compiled binaries. Can also be set across all languages with [`MISE_NODE__COMPILE`](https://github.com/jdx/mise#mise_node_compile1) +- `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_MIRROR_URL` [string]: overrides the default mirror used for downloading the distributions +- `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). + +## 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: + +```text +lodash +request +express +``` + +You can specify a non-default location of this file by setting a `MISE_NODE_DEFAULT_PACKAGES_FILE` variable. + +## `.nvmrc` and `.node-version` support + +mise uses a `.tool-versions` or `.mise.toml` 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 `.tool-versions`/`.mise.toml`. + +## "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. diff --git a/docs/lang/python.md b/docs/lang/python.md new file mode 100644 index 0000000000..ff0ef63ad4 --- /dev/null +++ b/docs/lang/python.md @@ -0,0 +1,195 @@ +# 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 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: + +```sh +mise use -g python@3.11 +``` + +You can also use multiple versions of python at the same time: + +```sh +$ mise use -g python@3.10 python@3.11 +$ python -V +3.10.0 +$ python3.11 -V +3.11.0 +``` + +## Configuration + +`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. + +### `python_pyenv_repo` + +* Type: `string` +* Env: `MISE_PYENV_REPO` +* Default: `https://github.com/pyenv/pyenv.git` + +The pyenv repo to get python-build from. + +### `python_compile` + +* Type: `bool` +* Env: `MISE_PYTHON_COMPILE` +* Default: [undefined] +* Values: + * `true` - always compile with python-build instead of downloading [precompiled binaries](#precompiled-python-binaries). + * `false` - always download precompiled binaries. + * [undefined] - use precompiled binary if one is available for the current platform, compile otherwise. + +### `python_precompiled_os` + +* Type: `string` +* Env: `MISE_PYTHON_PRECOMPILED_OS` +* Default: `"apple-darwin" | "unknown-linux-gnu" | "unknown-linux-musl"` + +Specify the OS to use for precompiled binaries. + +### `python_precompiled_arch` + +* Type: `string` +* Env: `MISE_PYTHON_PRECOMPILED_ARCH` +* Default: `"x86_64_v3" | "aarch64"` + +Specify the architecture to use for precompiled binaries. If on an old CPU, you may want to set this +to +`"x86_64"` for the most compatible binaries. +See for more information. + +### `python_patch_url` + +* Type: `string` +* Env: `MISE_PYTHON_PATCH_URL` + +A url to a patch file to pass to python-build. + +### `python_patches_directory` + +* Type: `string` +* Env: `MISE_PYTHON_PATCHES_DIRECTORY` + +A local directory containing patch files to pass to python-build. + +### `python_default_packages_file` + +* Type: `string` +* Env: `MISE_PYTHON_DEFAULT_PACKAGES_FILE` +* Default: `$HOME/.default-python-packages` + +Packages list to install with pip after installing a Python version. + +## 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: + +```text +ansible +pipenv +``` + +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/indygreg/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. + +That said, there are +some [quirks](https://github.com/indygreg/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 [`python_compile`](#python_compile) to `true`. + +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. + +## 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: + +```sh +CFLAGS="-I$(brew --prefix openssl)/include" \ +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 + +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 +brew unlink pkg-config +mise install python@latest +brew link pkg-config +``` + +Thus the entire script would look like: + +```sh +brew unlink pkg-config +CFLAGS="-I$(brew --prefix openssl)/include" \ + LDFLAGS="-L$(brew --prefix openssl)/lib" \ + mise install python@latest +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: + +```toml +[tools] +python = "3.11" # [optional] will be used for the venv + +[env] +_.python.venv = ".venv" # relative to this file's directory +_.python.venv = "/root/.venv" # can be absolute +_.python.venv = "{{env.HOME}}/.cache/venv/myproj" # can use templates +_.python.venv = { path = ".venv", create = true } # create the venv if it doesn't exist +``` + +The venv will need to be created manually with `python -m venv /path/to/venv` unless `create=true`. diff --git a/docs/lang/ruby.md b/docs/lang/ruby.md new file mode 100644 index 0000000000..2ce51278e0 --- /dev/null +++ b/docs/lang/ruby.md @@ -0,0 +1,72 @@ +# 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`. + +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: + +```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. You can check its +[README](https://github.com/rbenv/ruby-build/blob/master/README.md) +for additional settings and some troubleshooting. + +## Configuration + +`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 configuration variables: + +- `MISE_RUBY_INSTALL` [bool]: Build with ruby-install instead of ruby-build +- `MISE_RUBY_APPLY_PATCHES` [string]: A list of patches (files or URLs) to apply to the ruby source code +- `MISE_RUBY_VERBOSE_INSTALL` [bool]: Show verbose output during installation (passes --verbose to ruby-build) +- `MISE_RUBY_BUILD_OPTS` [string]: Command line options to pass to ruby-build when installing +- `MISE_RUBY_INSTALL_OPTS` [string]: Command line options to pass to ruby-install when installing (if MISE_RUBY_INSTALL=1) +- `MISE_RUBY_DEFAULT_PACKAGES_FILE` [string]: location of default gems file, defaults to `$HOME/.default-gems` + +## Default gems + +mise can automatically install a default set of gems right after installing a new ruby version. +To enable this feature, provide a `$HOME/.default-gems` file that lists one gem per line, for +example: + +```text +# supports comments +pry +bcat ~> 0.6.0 # supports version constraints +rubocop --pre # install prerelease version +``` + +## `.ruby-version` and `Gemfile` support + +mise uses a `.tool-versions` or `.mise.toml` file for auto-switching between software versions. +However it can also read ruby-specific version files `.ruby-version` or `Gemfile` +(if it specifies a ruby version). + +Create a `.ruby-version` file for the current version of ruby: + +```sh +ruby -v > .ruby-version +``` + +### Manually updating ruby-build + +ruby-build should update daily, however if you find versions do not yet exist you can force an +update: + +```bash +mise cache clean +mise ls-remote ruby +``` diff --git a/docs/lang/rust.md b/docs/lang/rust.md new file mode 100644 index 0000000000..ccd04bfa1a --- /dev/null +++ b/docs/lang/rust.md @@ -0,0 +1,40 @@ +# Rust + +Rust is not currently offered as a core plugin. In fact, I don't think you +should actually use mise for rust development. Rust has an official version +manager called [`rustup`](https://rustup.rs/) that is better than what any of +the current mise plugins offer. + +You install [rustup](https://rustup.rs/) with the following: + +```sh +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +That said, rust is still one of the most popular languages to use in mise. +A lot of users have success with it so if you'd like to keep all of your +languages configured the same, don't feel like using mise is a bad idea either. Especially if you're only a casual rust user. + +If you're a relatively heavy rust user making use of things like channel +overrides, components, and cross-compiling, then I think you really should +just be using rustup though. The experience will be better. + +If one day we could figure out a way to provide an equivalent experience with +mise, we could revisit this. We have discussed potentially using mise as a +"front-end" to rustup where there is one rustup install that mise just manages +so you could do something like this: + +```toml +[tools] +rust = "nightly" +``` + +Where that would basically be equivalent to: + +```sh +rustup override set nightly +``` + +Frankly though, this isn't high on my priority list. Use rustup. It's great. + +Kudos for writing rust too btw, I've really enjoyed it so far—this is my first rust project. diff --git a/docs/lefthook.yml b/docs/lefthook.yml new file mode 100644 index 0000000000..43b0fd0c5a --- /dev/null +++ b/docs/lefthook.yml @@ -0,0 +1,6 @@ +pre-commit: + commands: + build: + glob: "*" + run: npm run docs:build + interactive: true diff --git a/docs/node.md b/docs/node.md deleted file mode 100644 index 83ea937a48..0000000000 --- a/docs/node.md +++ /dev/null @@ -1 +0,0 @@ -Moved to [mise.jdx.dev/lang/node.html](https://mise.jdx.dev/lang/node.html). diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000000..e8478f8247 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,13 @@ +{ + "name": "@mise/docs", + "private": true, + "type": "module", + "devDependencies": { + "vitepress": "1.2.2" + }, + "scripts": { + "docs:dev": "vitepress dev", + "docs:build": "vitepress build", + "docs:preview": "vitepress preview" + } +} diff --git a/docs/paranoid.md b/docs/paranoid.md new file mode 100644 index 0000000000..c1b580d549 --- /dev/null +++ b/docs/paranoid.md @@ -0,0 +1,51 @@ +# Paranoid + +Paranoid is an optional behavior that locks mise down more to make it harder +for a bad actor to compromise your system. These are settings that I +personally do not use on my own system because I find the behavior too +restrictive for the benefits. + +Paranoid mode can be enabled with either `MISE_PARANOID=1` or a setting: + +```sh +mise settings set paranoid 1 +``` + +## Config files + +Normally `mise` will make sure some config files are "trusted" before loading +them. This will prompt you to confirm that you want to load the file, e.g.: + +```sh +$ mise install +mise ~/src/mise/.tool-versions is not trusted. Trust it [y/n]? +``` + +Generally only potentially dangerous config files are checked such as files +that use templates (which can execute arbitrary code) or that set env vars. +Under paranoid, however, all config files must be trusted first. + +Also, in normal mode, a config file only needs to be trusted a single time. +In paranoid, the contents of the file are hashed to check if the file changes. +If you change your config file, you'll need to trust it again. + +## Community plugins + +Community plugins can not be directly installed via short-name under paranoid. +You can install plugins that are either core, maintained by the mise team, +or plugins that mise has marked as "first-party"—meaning plugins developed by +the same team that builds the tool the plugin installs. + +Other than that, say for "shfmt", you'll need to specify the full git repo +to install: + +```sh +mise plugin install shfmt https://github.com/luizm/asdf-shfmt +``` + +Unlike in normal mode where `mise plugin install shfmt` would be sufficient. + +## More? + +If you have suggestions for more that could be added to paranoid, please let +me know. diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 0000000000..2568723f02 --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,48 @@ +# Plugins + +mise uses asdf's plugin ecosystem under the hood. These plugins contain shell scripts like +`bin/install` (for installing) and `bin/list-all` (for listing all of the available versions). + +See for the list of built-in plugins shorthands. See asdf's +[Create a Plugin](https://asdf-vm.com/plugins/create.html) for how to create your own or just learn +more about how they work. + +## Core Plugins + +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 a 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 plugin ls --core`. + +- [Bun](/lang/bun) +- [Deno](/lang/deno) +- [Erlang](/lang/erlang) +- [Go](/lang/go) +- [Java](/lang/java) +- [NodeJS](/lang/node) +- [Python](/lang/python) +- [Ruby](/lang/ruby) + +## Plugin Authors + + is a GitHub organization for community-developed plugins. +See [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md) for more details on how plugins here are treated differently. + +If you'd like your plugin to be hosted here please let me know (GH discussion or discord is fine) +and I'd be happy to host it for you. + +## Plugin Options + +mise has support for "plugin options" which is configuration specified in `.mise.toml` to change behavior +of plugins. One example of this is virtualenv on python runtimes: + +```toml +[tools] +python = {version='3.11', virtualenv='.venv'} +``` + +This will be passed to all plugin scripts as `MISE_TOOL_OPTS__VIRTUALENV=.venv`. The user can specify +any option and it will be passed to the plugin in that format. + +Currently this only supports simple strings, but we can make it compatible with more complex types +(arrays, tables) fairly easily if there is a need for it. diff --git a/docs/profiles.md b/docs/profiles.md new file mode 100644 index 0000000000..e22b1cf038 --- /dev/null +++ b/docs/profiles.md @@ -0,0 +1,39 @@ +# Profiles + +It's possible to have separate `.mise.toml` files in the same directory for different +environments like `development` and `production`. To enable, set `MISE_ENV` to an environment like +`development` or `production`. mise will then look for a `.mise.{MISE_ENV}.toml` file in the current directory. + +mise will also look for "local" files like `.mise.local.toml` and `.mise.{MISE_ENV}.local.toml` in +the current directory. 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 (bottom overrides top): + +- `.config/mise/config.toml` +- `mise/config.toml` +- `mise.toml` +- `.mise/config.toml` +- `.mise.toml` +- `.config/mise/config.local.toml` +- `mise/config.local.toml` +- `mise.local.toml` +- `.mise/config.local.toml` +- `.mise.local.toml` +- `.config/mise/config.{MISE_ENV}.toml` +- `mise/config.{MISE_ENV}.toml` +- `mise.{MISE_ENV}.toml` +- `.mise/config.{MISE_ENV}.toml` +- `.mise.{MISE_ENV}.toml` +- `.config/mise/config.{MISE_ENV}.local.toml` +- `mise/config.{MISE_ENV}.local.toml` +- `.mise/config.{MISE_ENV}.local.toml` +- `.mise.{MISE_ENV}.local.toml` + +Use `mise doctor` to see which files are being used. + +::: warning +Note that currently modifying `MISE_DEFAULT_CONFIG_FILENAME` to something other than `.mise.toml` +will not work with this feature. For now, it will disable it entirely. This may change in the +future. +::: diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md new file mode 100644 index 0000000000..9d9b8a2bf3 --- /dev/null +++ b/docs/project-roadmap.md @@ -0,0 +1,33 @@ +# Project Roadmap + +Issues marked ["enhancements"](https://github.com/jdx/mise/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) are the best way to read about ideas for future +functionality. As far as general scope however, these are likely going to be focuses for 2024: + +* Tasks - this is the newest headline feature of mise and needs to be refined, tested, and iterated on before it can come out of experimental +* Documentation website - we've outgrown what is mostly a single README +* Supply chain hardening - securing mise is very important and this topic has had a lot of interest from the community. We plan to make several improvements on this front +* Improved python development - better virtualenv integration, precompiled python binaries, and other areas are topics that frequently come up to improve +* Improved plugin development - it's unclear what we'll do exactly but in general we want to make the experience of vending tools for asdf/mise to be better and safer. +* GUI/TUI - While we're all big CLI fans, it still would be great to better visualize what tools are available, what your configuration is, and other things via some kind of UI. + +## Versioning + +mise uses [Calver](https://calver.org/) versioning (`2024.1.0`). +Breaking changes will be few but when they do happen, +they will be communicated in the CLI with plenty of notice whenever possible. + +Rather than have SemVer major releases to communicate change in large releases, +new functionality and changes can be opted-into with settings like `experimental = true`. +This way plugin authors and users can +test out new functionality immediately without waiting for a major release. + +The numbers in Calver (YYYY.MM.RELEASE) simply represent the date of the release—not compatibility +or how many new features were added. +Each release will be small and incremental. + +## Anti-goals + +* Dependency management - mise expects you to have system dependencies (like openssl or readline) already setup and configured. This makes it different than tools like nix which manage all dependencies for you. While this seems like an obvious downside, it actually ends up making mise far easier to use than nix. That said, we would like to make managing system dependencies easier where we can but this is likely going to be simply via better docs and error messages. +* DevOps tooling - mise is designed with local development in mind. While there are certainly many devs using it for production/server roles which we support and encourage, that will never be the our focus on the roadmap. Building a better ansible/terraform/kubernetes just isn't the goal. +* Remote task caching - turbopack, moonrepo, and many others are trying to solve this (major) problem. mise's task runner will likely always just be a simple convenience around executing scripts. +* Windows support - I don't have a Windows machine and I think asdf/mise's focus on Unix tools will make supporting (non-WSL) Windows challenging if not impossible. Unless someone else wants to take on the challenge of building a Windows port I would not expect to see it happen. diff --git a/docs/public/android-chrome-192x192.png b/docs/public/android-chrome-192x192.png new file mode 100755 index 0000000000000000000000000000000000000000..5a62092b4897c7af8d5b043fd2925013f9dece77 GIT binary patch literal 5311 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 SeKEZw3DChBXnaz$4gEj#i_mBQ literal 0 HcmV?d00001 diff --git a/docs/public/android-chrome-512x512.png b/docs/public/android-chrome-512x512.png new file mode 100755 index 0000000000000000000000000000000000000000..ed95d3c8db574381f39b1334e675f91d11bf4617 GIT binary patch literal 25069 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 literal 0 HcmV?d00001 diff --git a/docs/public/apple-touch-icon.png b/docs/public/apple-touch-icon.png new file mode 100755 index 0000000000000000000000000000000000000000..10fac23687d6618171b48a6eb5a7f3c246e3e949 GIT binary patch literal 4792 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 Z_?#7<2S%y4(4;7U!EF=0N*(7X{{to^4@>|6 literal 0 HcmV?d00001 diff --git a/docs/public/favicon-16x16.png b/docs/public/favicon-16x16.png new file mode 100755 index 0000000000000000000000000000000000000000..bfe60ca6a350f09433e06896bb400e921f707de1 GIT binary patch literal 262 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`jKx9jP7LeL$-D$|4tTmahFJLD zoxG8+SwWz!o~L=8k7UX!`!VxNL$&pR&dCK&71vYIvCLO}?hQK!Zyn z`NFo`3GVD`w@wI>WB6?2tjYR3Cc<7eHA{78llNVHvp@fg?=nnW8ONwxCfxz_3xlVt KpUXO@geCyG8)jbs literal 0 HcmV?d00001 diff --git a/docs/public/favicon-32x32.png b/docs/public/favicon-32x32.png new file mode 100755 index 0000000000000000000000000000000000000000..85139b16460419d114c1488e63fbf66fea117f81 GIT binary patch literal 462 zcmV;<0WtoGP)Px$h)G02R9HvtmA#IFP!NR=(kMKHMqfcoV+p7Ul~JG3koc2WU?(N5T3PrMN&&i= zN!Sqf>UB34*@9a_a_5_KX3o_BJW%4%Du7CXN`Zf?K(pC|rfIlbE`_FqFb7(#77m94 zYPA|BlL@xlEkisW>N86SK;55CCm4o->-CD+Y=+HdQ-~5zlW;T|VX;`C(P-dyyJ0$= z76S1yit`Yu5-P2bz6Du`D2mvQ)oP{84k-Xt%0sxW3*YyZK)eM&mB!;S&qTdm$9})Z zU@-VBz;HN(=XvD-P;u&>){^FcEZFUKN^(JJf#W#bIjv(lgzNQMSuni>ux*=*r=8OV zq{USw<5K|3vbeZun%wz(KF4yoY@~&S1!`|^ zS8eEXb8|z*V$qUO2ODGJYY*~sN`t~l*}?ays( zZOX>!>8S&wy|3Fd#$R1sQJC@U8{?TrHy>_w;1985EbO@T@v6i4`T6-!W4-Ktf;Jgq z_=I&PFY|Yqu|9dEz;h~X=`orEt$~0VaNFO)ewVO^)z;P;xvs8`N@d;`gZS_2>Z0!M zZr3@6z4P;P%l>QMkIm2Mi!pxvcXoEt^Yb&kyu8r(__zZD`!5sl7#N_ZrzZ;!97kL@ z1_uX~7R+QgPo!$57=xA)5WBuiI2W6bT!GAuVS8Fdg2M=+t zH^2Z6fWxc@{aOFtp*5g25U~cNxzC$$P9l$J#SfYFIf?#mNg3!pS972>pf#X1@JThm z|L^%JdB5Pk{2WIKpEzU09h*7h&eTt?udg@mOryXLd$=P+SuTE@pH59p(f$3sI#FH?#hdAfp9ApkKcd!u!|2XG;eSI}(L=2moo1XIkzjpom z(LMKJ{WJIfq952?TwJ7whX*4DaJjX$Wr=}(mC_-%hbc?h^jn|JW@%|@N!_V%5SWLf zqa#C0jLWahxcjxVw9xkUwj&121AhCEbo}58F)S}H8}~n$3up=72XhQbjs;p;Sy^$+ z1FuVr9cA1a@#`;>$v2zJ6t*xyY z`y2LLtV!IS^pf$vy}f~cm8u0l^aJj({&2z`R}K0B?|XZDhHikL-zyMTl63>@tE;OH z><0%2#$KFM{EQv%l$@~slzX2`LOiS){H}yku~4M-^>t(KO#)6g4EUX@T{DPde}CWd z4(c|x(sfNuO$xhNGx&_P2XR#zUpfEyeTG>x_*^a65gYEg89&y@-Q8WqJHMxui@(zC z&=1ZNj*pLNW@e@;G-Kxs|I1?iL1}N(&-z|QYd~v2Yd~v2Yd~v2Yan(FNXm8641{Cg E4*`(PfdBvi literal 0 HcmV?d00001 diff --git a/docs/public/site.webmanifest b/docs/public/site.webmanifest new file mode 100755 index 0000000000..45dc8a2065 --- /dev/null +++ b/docs/public/site.webmanifest @@ -0,0 +1 @@ +{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"} \ No newline at end of file diff --git a/docs/python.md b/docs/python.md deleted file mode 100644 index c37f95080b..0000000000 --- a/docs/python.md +++ /dev/null @@ -1 +0,0 @@ -Moved to [mise.jdx.dev/lang/python.html](https://mise.jdx.dev/lang/python.html) diff --git a/docs/rtx.md b/docs/rtx.md new file mode 100644 index 0000000000..2f35f3bece --- /dev/null +++ b/docs/rtx.md @@ -0,0 +1,51 @@ +# Coming from rtx + +`mise` was formerly called `rtx`. The name was changed to avoid confusion with Nvidia's +line of graphics cards. This wasn't a legal issue, but just general confusion. When +people first hear about the project or see it posted they wouldn't realize it was talking +about a CLI tool. It was a bit difficult to search for on Google but also places like +Twitter and in Slack searches and things. This was the top complaint about `rtx` and +many people were fairly outspoken about disliking the name for this reason. `rtx` was +supposed to be a working title that I intended to change but never got around to doing. +This change should've happened earlier when there were fewer users and I apologize for +not having done that sooner knowing that this was likely going to be necessary at some point. + +To upgrade from `rtx` to `mise`, simply install `mise` and it should automatically +migrate its internal directories, moving `~/.local/share/rtx/installs/*` to `~/.local/share/mise/installs/*` +(skipping python & ruby which cannot be moved), `~/.local/share/rtx/plugins` to `~/.local/share/mise/plugins`, +and `~/.config/rtx` to `~/.config/mise` (if the destination does not exist). Python and Ruby +installs will need to be reinstalled with `mise install`. + +`mise` will continue reading `.rtx.toml` files for some time but that eventually will +be deprecated so please rename them to `.mise.toml`. `mise` will not read from `RTX_*` +env vars so those will need to be changed to `MISE_*`. Anything using a local `.rtx` or +`.config/rtx` directory will need to be moved to `.mise`/`.config/mise`. + +I apologize if this migration is not seamless however I think moving to a name that +is easier to search for and avoids confusion is better for everyone. I also apologize +for it being abrupt—I simply couldn't think of a way to "slow roll" this change out +while also keeping the GitHub repo. + +Users of the `rtx-action` GitHub action will need to switch to `mise-action` (and also +bump the major version to v2). + +If you build infrastructure where users may still be calling `rtx activate` in their +shell rc scripts, you can create a symlink `ln -s /path/to/mise /path/to/rtx` so +`rtx activate` still functions. + +For , we're using `~/.local/bin/mise` +as the executable PATH instead of the old directory `~/.local/share/rtx/bin/mise` +to keep things a bit cleaner. You can still use the old style if you like by setting +`MISE_INSTALL_PATH`. + +If you use shims, a `mise reshim` will be necessary to update the shims. + +Thanks for trying out my little CLI tool by the way. I find this project incredibly +fulfilling to work on and seeing people have success using. I have +tremendous passion for building dev tools and the ideas in `mise` are the product of +me thinking about building a tool like this for over a decade. + +If you aren't happy with `mise` or the way I'm running this project, even in a tiny way, +please let me know. You can [contact me privately](/about#contact) if you like. I certainly +won't take offense and I would prefer you say something rather than nothing. Otherwise +I'll never know. diff --git a/docs/ruby.md b/docs/ruby.md deleted file mode 100644 index f1be7cbba6..0000000000 --- a/docs/ruby.md +++ /dev/null @@ -1 +0,0 @@ -Moved to [mise.jdx.dev/lang/ruby.html](https://mise.jdx.dev/lang/ruby.html). diff --git a/docs/tasks/index.md b/docs/tasks/index.md new file mode 100644 index 0000000000..265980fd36 --- /dev/null +++ b/docs/tasks/index.md @@ -0,0 +1,22 @@ +# Tasks + +You can define tasks in `.mise.toml` files or as standalone shell scripts. These are useful for things like +running linters, tests, builders, servers, and other tasks that are specific to a project. Of course, +tasks launched with mise will include the mise environment—your tools and env vars defined in `.mise.toml`. + +Here's my favorite features about mise's task runner: + +- building dependencies in parallel—by default with no configuration required +- last-modified checking to avoid rebuilding when there are no changes—requires minimal config +- `mise watch` to automatically rebuild on changes—no configuration required, but it helps +- ability to write tasks as actual bash script files and not inside yml/json/toml strings that lack syntax highlighting and linting/checking support + +::: warning +This is an experimental feature. It is not yet stable and will likely change. Some of the docs +may not be implemented, may be implemented incorrectly, or the docs may need to be updated. +Please give feedback early since while it's experimental it's much easier to change. +::: + +## Task Environment Variables + +- `root` - the root of the project, defaults to the directory of the `.mise.toml` file diff --git a/docs/tasks/running-tasks.md b/docs/tasks/running-tasks.md new file mode 100644 index 0000000000..7d60548c84 --- /dev/null +++ b/docs/tasks/running-tasks.md @@ -0,0 +1,112 @@ +# Running Tasks + +See available tasks with `mise tasks`. To show tasks hidden with property `hide=true`, use the option `--hidden`. + +List dependencies of tasks with `mise task deps [tasks]...`. + +Run a task with `mise task run`, `mise run`, or just `mise r`. +You might even want to make a shell alias like `alias mr='mise run --'` since this is likely a common command. + +By default, tasks will execute with a maximum of 4 parallel jobs. Customize this with the `--jobs` option, +`jobs` setting or `MISE_JOBS` environment variable. The output normally will be by line, prefixed with the task +label. By printing line-by-line we avoid interleaving output from parallel executions. However, if +--jobs == 1, the output will be set to `interleave`. + +To just print stdout/stderr directly, use `--interleave`, the `task_output` setting, or `MISE_TASK_OUTPUT=interleave`. + +Stdin is not read by default. To enable this, set `raw = true` on the task that needs it. This will prevent +it running in parallel with any other task-a RWMutex will get a write lock in this case. + +Extra arguments will be passed to the task, for example, if we want to run in release mode: + +```bash +mise run build --release +``` + +If there are multiple commands, the args are only passed to the last command. + +Multiple tasks/arguments can be separated with this `:::` delimiter: + +```bash +mise run build arg1 arg2 ::: test arg3 arg4 +``` + +mise will run the task named "default" if no task is specified—and you've created one named "default". You can also alias a different task to "default". + +```bash +mise run +``` + +## Task Grouping + +Tasks can be grouped semantically by using name prefixes separated with `:`s. +For example all testing related tasks may begin with `test:`. Nested grouping +can also be used to further refine groups and simplify pattern matching. +For example running `mise run test:**:local` will match`test:units:local`, +`test:integration:local` and `test:e2e:happy:local` +(See [Wildcards](#wildcards) for more information). + +## Wildcards + +Glob style wildcards are supported when running tasks or specifying tasks +dependencies. + +Available Wildcard Patterns: + +- `?` matches any single character +- `*` matches 0 or more characters +- `**` matches 0 or more groups +- `{glob1,glob2,...}` matches any of the comma-separated glob patterns +- `[ab,...]` matches any of the characters or ranges `[a-z]` +- `[!ab,...]` matches any character not in the character set + +### Examples + +`mise run generate:{completions,docs:*}` + +And with dependencies: + +```toml +[tasks."lint:eslint"] # using a ":" means we need to add quotes +run = "eslint ." +[tasks."lint:prettier"] +run = "prettier --check ." +[tasks.lint] +depends = ["lint:*"] +``` + +## Running on file changes + +It's often handy to only execute a task if the files it uses changes. For example, we might only want +to run `cargo build` if an ".rs" file changes. This can be done with the following config: + +```toml +[tasks.build] +description = 'Build the CLI' +run = "cargo build" +sources = ['Cargo.toml', 'src/**/*.rs'] # skip running if these files haven't changed +outputs = ['target/debug/mycli'] +``` + +Now if `target/debug/mycli` is newer than `Cargo.toml` or any ".rs" file, the task will be skipped. This uses last modified timestamps. +It wouldn't be hard to add checksum support. + +## Watching files + +Run a task when the source changes with `mise watch`: + +```bash +mise watch -t build +``` + +Currently this just shells out to watchexec-which you can install however you want including with mise: `mise use -g watchexec@latest`. +This may change in the future. + +Arguments to `mise watch` will be forwarded onto watchexec. For example, to print diagnostic info: + +```bash +mise watch -t build -- --print-events --verbose +``` + +See watchexec's help with `watchexec --help` or `mise watch -- --help` to see +all of the options. diff --git a/docs/tasks/script-tasks.md b/docs/tasks/script-tasks.md new file mode 100644 index 0000000000..0b8992dbeb --- /dev/null +++ b/docs/tasks/script-tasks.md @@ -0,0 +1,61 @@ +# Script Tasks + +In addition to defining tasks through the configuration, they can also be defined as standalone script files in +`.mise/tasks/:task_name` such as the following build script for cargo: + +```bash +#!/usr/bin/env bash +# mise description="Build the CLI" +cargo build +``` + +Ensure that the file is executable, otherwise mise will not be able to detect it. + +:::tip +The `mise:description` comment is optional but recommended. It will be used in the output of `mise tasks`. +The other configuration for "script" tasks is supported in this format so you can specify things like the +following-note that this is parsed a TOML table: + +```bash +# mise alias="b" +# mise sources=["Cargo.toml", "src/**/*.rs"] +# mise outputs=["target/debug/mycli"] +# mise env={RUST_BACKTRACE = "1"} +# mise depends=["lint", "test"] +``` + +Assuming that file was located in `.mise/tasks/build`, it can then be run with `mise run build` (or with its alias: `mise run b`). +This script can be edited with by running `mise task edit build` (using $EDITOR). If it doesn't exist it will be created. +These are convenient for quickly making new scripts. Having the code in a bash file and not TOML helps make it work +better in editors since they can do syntax highlighting and linting more easily. They also still work great for non-mise users—though +of course they'll need to find a different way to install their dev tools the tasks might use. +::: + +## Task Grouping + +Script tasks in `.mise/tasks`, `mise/tasks`, or `.config/mise/tasks` can be grouped into +sub-directories which will automatically apply prefixes to their names +when loaded. + +### Example + +With a folder structure like below: + +```text +.mise +└── tasks + ├── build + └── test + ├── integration + └── units +``` + +Running `mise tasks` will give the below output: + +```text +$ mise tasks +Name Description Source +build .../.mise/tasks/build +test:integration .../.mise/tasks/test/integration +test:units .../.mise/tasks/test/units +``` diff --git a/docs/tasks/toml-tasks.md b/docs/tasks/toml-tasks.md new file mode 100644 index 0000000000..e46aa9d2e7 --- /dev/null +++ b/docs/tasks/toml-tasks.md @@ -0,0 +1,43 @@ +# TOML-based Tasks + +Tasks can also be defined in `.mise.toml` files in different ways. This is a more "traditional" method of defining tasks: + +```toml +[tasks.cleancache] +run = "rm -rf .cache" +hide = true # hide this task from the list + +[tasks.clean] +depends = ['cleancache'] +run = "cargo clean" # runs as a shell command + +[tasks.build] +description = 'Build the CLI' +run = "cargo build" +alias = 'b' # `mise run b` + +[tasks.test] +description = 'Run automated tests' +run = [ # multiple commands are run in series + 'cargo test', + './scripts/test-e2e.sh', +] +dir = "{{cwd}}" # run in user's cwd, default is the project's base directory + +[tasks.lint] +description = 'Lint with clippy' +env = {RUST_BACKTRACE = '1'} # env vars for the script +# you can specify a multiline script instead of individual commands +run = """ +#!/usr/bin/env bash +cargo clippy +""" + +[tasks.ci] # only dependencies to be run +description = 'Run CI tasks' +depends = ['build', 'lint', 'test'] + +[tasks.release] +description = 'Cut a new release' +file = 'scripts/release.sh' # execute an external script +``` diff --git a/docs/team.md b/docs/team.md new file mode 100644 index 0000000000..6c0617bc0f --- /dev/null +++ b/docs/team.md @@ -0,0 +1,61 @@ + + +# Team + +Jeff Dickey is the primary developer behind mise. He does the bulk +of development for the project. + + + +## Advisory Board + +The advisory board helps make important decisions about the project such as: + +* What features should be on the roadmap +* When should functionality move from experimental to stable +* If/when/how features should be deprecated + + + +## Contributors + +mise is an open source project which welcomes [contributions](https://github.com/jdx/mise/graphs/contributors). +We're grateful for those that have volunteered their work for the project. diff --git a/docs/templates.md b/docs/templates.md new file mode 100644 index 0000000000..c3feb9a477 --- /dev/null +++ b/docs/templates.md @@ -0,0 +1,31 @@ +# Templates + +Templates are used in the following locations: + +- `.tool-versions` files +- `.mise.toml` files for most configuration +- _(Submit a ticket if you want to see it used elsewhere!)_ + +The following context objects are available inside templates: + +- `env: HashMap` – current environment variables +- `config_root: PathBuf` – directory containing the `.mise.toml` file + +As well as these functions: + +- `exec(command: &str) -> String` – execute a command and return the output + +Templates are parsed with [tera](https://keats.github.io/tera/docs/)—which is quite powerful. For +example, this snippet will get the directory name of the project: + +```toml +[env] +PROJECT_NAME = "{{config_root | split(pat='/') | last}}" +``` + +Here's another using `exec()`: + +```toml +[aliases] +current = "{{exec(command='node --version')}}" +``` diff --git a/docs/tips-and-tricks.md b/docs/tips-and-tricks.md new file mode 100644 index 0000000000..0c428a7ad0 --- /dev/null +++ b/docs/tips-and-tricks.md @@ -0,0 +1,82 @@ +# Tips & Tricks + +An assortment of helpful tips for using `mise`. + +## macOS Rosetta + +If you have a need to run tools as x86_64 on Apple Silicon, this can be done with mise however you'll currently +need to use the x86_64 version of mise itself. There is an [outstanding issue](https://github.com/jdx/mise/issues/405) +to support this with an env var like MISE_ARCH=x86_64 to make it more seamless. + +A common reason for doing this is to support compiling node <=14. + +First, you'll need a copy of mise that's built for x86_64: + +```sh +$ mkdir -p ~/.local/bin +$ curl https://mise.jdx.dev/mise-latest-macos-x64 > ~/.local/bin/mise-x64 +$ chmod +x ~/.local/bin/mise-x64 +$ ~/.local/bin/mise-x64 --version +mise 2024.x.x +``` + +::: warning +If `~/.local/bin` is not in PATH, you'll need to prefix all commands with `~/.local/bin/mise-x64`. +::: + +Now you can use `mise-x64` to install tools: + +```sh +mise-x64 use -g node@20 +``` + +## Shebang + +You can specify a tool and its version in a shebang without needing to first +setup `.tool-versions`/`.mise.toml` config: + +```typescript +#!/usr/bin/env -S mise x node@20 -- node +// "env -S" allows multiple arguments in a shebang +console.log(`Running node: ${process.version}`); +``` + +This can also be useful in environments where mise isn't activated +(such as a non-interactive session). + +## CI/CD + +Using mise in CI/CD is a great way to synchronize tool versions for dev/build. + +### GitHub Actions + +mise is pretty easy to use without an action: + +```yaml +jobs: + build: + steps: + - run: | + curl https://mise.run | sh + echo "$HOME/.local/bin" >> $GITHUB_PATH + echo "$HOME/.local/share/mise/shims" >> $GITHUB_PATH +``` + +Or you can use the custom action [`jdx/mise-action`](https://github.com/jdx/mise-action): + +```yaml +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: jdx/mise-action@v1 + - run: node -v # will be the node version from `.mise.toml`/`.tool-versions` +``` + +## `mise set` + +Instead of manually editing `.mise.toml` to add env vars, you can use `mise set` instead: + +```sh +mise set NODE_ENV=production +``` diff --git a/scripts/publish-r2.sh b/scripts/publish-r2.sh index fefa21985c..6b27fa4093 100755 --- a/scripts/publish-r2.sh +++ b/scripts/publish-r2.sh @@ -8,4 +8,4 @@ export AWS_ACCESS_KEY_ID=$CLOUDFLARE_ACCESS_KEY_ID export AWS_SECRET_ACCESS_KEY=$CLOUDFLARE_SECRET_ACCESS_KEY export AWS_S3_BUCKET=mise -./mise/scripts/publish-s3.sh +./scripts/publish-s3.sh diff --git a/scripts/publish-s3.sh b/scripts/publish-s3.sh index c9456c1d13..076bf81447 100755 --- a/scripts/publish-s3.sh +++ b/scripts/publish-s3.sh @@ -12,9 +12,9 @@ aws s3 cp "$RELEASE_DIR" "s3://$AWS_S3_BUCKET/" --cache-control "$cache_day" --n aws s3 cp "$RELEASE_DIR/VERSION" "s3://$AWS_S3_BUCKET/" --cache-control "$cache_day" --no-progress --content-type "text/plain" aws s3 cp "$RELEASE_DIR/install.sh" "s3://$AWS_S3_BUCKET/" --cache-control "$cache_day" --no-progress --content-type "text/plain" aws s3 cp "$RELEASE_DIR/install.sh.sig" "s3://$AWS_S3_BUCKET/" --cache-control "$cache_day" --no-progress -aws s3 cp "./mise/schema/mise.json" "s3://$AWS_S3_BUCKET/schema/mise.json" --cache-control "$cache_day" --no-progress --content-type "application/json" -aws s3 cp "./mise/schema/settings.json" "s3://$AWS_S3_BUCKET/schema/settings.json" --cache-control "$cache_day" --no-progress --content-type "application/json" -aws s3 cp "./mise/schema/mise.plugin.json" "s3://$AWS_S3_BUCKET/schema/mise.plugin.json" --cache-control "$cache_day" --no-progress --content-type "application/json" +aws s3 cp "./schema/mise.json" "s3://$AWS_S3_BUCKET/schema/mise.json" --cache-control "$cache_day" --no-progress --content-type "application/json" +aws s3 cp "./schema/settings.json" "s3://$AWS_S3_BUCKET/schema/settings.json" --cache-control "$cache_day" --no-progress --content-type "application/json" +aws s3 cp "./schema/mise.plugin.json" "s3://$AWS_S3_BUCKET/schema/mise.plugin.json" --cache-control "$cache_day" --no-progress --content-type "application/json" aws s3 cp artifacts/rpm/mise.repo "s3://$AWS_S3_BUCKET/rpm/" --cache-control "$cache_day" --no-progress aws s3 cp artifacts/rpm/packages/ "s3://$AWS_S3_BUCKET/rpm/packages/" --cache-control "$cache_week" --no-progress --recursive diff --git a/scripts/release.sh b/scripts/release.sh index 6650af15d9..0ef1b2a9ca 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -5,8 +5,8 @@ echo "::group::Setup" git config --global user.name mise-en-dev git config --global user.email 123107610+mise-en-dev@users.noreply.github.com -BASE_DIR="$(cd mise && pwd)" -MISE_VERSION=$(cd mise && ./scripts/get-version.sh) +BASE_DIR="$(pwd)" +MISE_VERSION=$(./scripts/get-version.sh) RELEASE_DIR=releases export BASE_DIR MISE_VERSION RELEASE_DIR rm -rf "${RELEASE_DIR:?}/$MISE_VERSION" @@ -65,28 +65,16 @@ gpg --clearsign -u 8B81C9D17413A06D SHASUMS512.asc popd echo "::group::install.sh" -./mise/scripts/render-install.sh >"$RELEASE_DIR"/install.sh +./scripts/render-install.sh >"$RELEASE_DIR"/install.sh chmod +x "$RELEASE_DIR"/install.sh shellcheck "$RELEASE_DIR"/install.sh gpg -u 8B81C9D17413A06D --output "$RELEASE_DIR"/install.sh.sig --sign "$RELEASE_DIR"/install.sh if [[ "$DRY_RUN" != 1 ]]; then echo "::group::Publish npm @jdxcode/mise" - NPM_PREFIX=@jdxcode/mise ./mise/scripts/release-npm.sh + NPM_PREFIX=@jdxcode/mise ./scripts/release-npm.sh # echo "::group::Publish npm mise-cli" - # NPM_PREFIX=mise-cli ./mise/scripts/release-npm.sh + # NPM_PREFIX=mise-cli ./scripts/release-npm.sh echo "::group::Publish r2" - ./mise/scripts/publish-r2.sh + ./scripts/publish-r2.sh fi - -echo "::group::Publish mise-docs" -cp ./mise/docs/registry.md ./mise-docs/registry.md -cp ./mise/docs/cli-reference.md ./mise-docs/cli/index.md -pushd mise-docs -if [[ -z $(git status -s) ]]; then - echo "No changes to docs" -else - git add cli/index.md registry.md - git commit -m "mise ${MISE_VERSION#v}" -fi -popd diff --git a/src/cli/render_help.rs b/src/cli/render_help.rs index f72f3f7a12..1e108487fc 100644 --- a/src/cli/render_help.rs +++ b/src/cli/render_help.rs @@ -14,7 +14,7 @@ pub struct RenderHelp {} impl RenderHelp { pub fn run(self) -> Result<()> { - let readme = file::read_to_string("docs/cli-reference.md")?; + let readme = file::read_to_string("docs/cli/index.md")?; let mut current_readme = readme.split(""); let mut doc = String::new(); @@ -23,7 +23,7 @@ impl RenderHelp { doc.push_str(render_commands().as_str()); doc.push_str(current_readme.next().unwrap()); doc = remove_trailing_spaces(&doc) + "\n"; - file::write("docs/cli-reference.md", &doc)?; + file::write("docs/cli/index.md", &doc)?; Ok(()) } } @@ -125,9 +125,9 @@ mod tests { #[test] fn test_render_help() { reset(); - file::create_dir_all("docs").unwrap(); + file::create_dir_all("docs/cli").unwrap(); file::write( - "docs/cli-reference.md", + "docs/cli/index.md", indoc! {r#" @@ -135,8 +135,8 @@ mod tests { ) .unwrap(); assert_cli!("render-help"); - let readme = fs::read_to_string("docs/cli-reference.md").unwrap(); + let readme = fs::read_to_string("docs/cli/index.md").unwrap(); assert!(readme.contains("# Commands")); - file::remove_file("docs/cli-reference.md").unwrap(); + file::remove_file("docs/cli/index.md").unwrap(); } } diff --git a/src/shell/nushell.rs b/src/shell/nushell.rs index a2d83e25d3..5a32641b5e 100644 --- a/src/shell/nushell.rs +++ b/src/shell/nushell.rs @@ -109,13 +109,15 @@ impl Shell for Nushell { #[cfg(test)] mod tests { use insta::assert_snapshot; + use test_log::test; - use crate::test::replace_path; + use crate::test::{replace_path, reset}; use super::*; #[test] fn test_hook_init() { + reset(); let nushell = Nushell::default(); let exe = Path::new("/some/dir/mise"); assert_snapshot!(nushell.activate(exe, " --status".into())); @@ -123,22 +125,26 @@ mod tests { #[test] fn test_set_env() { + reset(); assert_snapshot!(Nushell::default().set_env("FOO", "1")); } #[test] fn test_prepend_env() { + reset(); let sh = Nushell::default(); assert_snapshot!(replace_path(&sh.prepend_env("PATH", "/some/dir:/2/dir"))); } #[test] fn test_unset_env() { + reset(); assert_snapshot!(Nushell::default().unset_env("FOO")); } #[test] fn test_deactivate() { + reset(); let deactivate = Nushell::default().deactivate(); assert_snapshot!(replace_path(&deactivate)); } diff --git a/src/toolset/tool_version_request.rs b/src/toolset/tool_version_request.rs index d7584629fb..f3083cb2de 100644 --- a/src/toolset/tool_version_request.rs +++ b/src/toolset/tool_version_request.rs @@ -204,10 +204,13 @@ impl Display for ToolRequest { #[cfg(test)] mod tests { use super::version_sub; + use crate::backend::reset; use pretty_assertions::assert_str_eq; + use test_log::test; #[test] fn test_version_sub() { + reset(); assert_str_eq!(version_sub("18.2.3", "2"), "16"); assert_str_eq!(version_sub("18.2.3", "0.1"), "18.1"); }