From ac2bf055cbfb5958ca2db8a67017a32eefc838b1 Mon Sep 17 00:00:00 2001 From: Jeff Dickey <216188+jdx@users.noreply.github.com> Date: Fri, 27 Sep 2024 19:10:31 -0500 Subject: [PATCH] feat: improving task docs --- .markdownlintignore | 5 +- .mise.toml | 8 +- .mise/tasks/filetask | 1 + Cargo.lock | 13 +- Cargo.toml | 4 +- docs/.vitepress/config.ts | 197 +- docs/cli/activate.md | 39 +- docs/cli/alias.md | 20 + docs/cli/alias/get.md | 19 +- docs/cli/alias/ls.md | 26 +- docs/cli/alias/set.md | 26 +- docs/cli/alias/unset.md | 21 +- docs/cli/asdf.md | 11 - docs/cli/backends.md | 7 + docs/cli/backends/ls.md | 22 +- docs/cli/bin-paths.md | 6 +- docs/cli/cache.md | 10 + docs/cli/cache/clear.md | 14 +- docs/cli/cache/prune.md | 27 +- docs/cli/completion.md | 20 +- docs/cli/config.md | 16 + docs/cli/config/generate.md | 18 +- docs/cli/config/get.md | 24 +- docs/cli/config/ls.md | 14 +- docs/cli/config/set.md | 39 +- docs/cli/current.md | 13 +- docs/cli/deactivate.md | 8 +- docs/cli/direnv.md | 13 + docs/cli/direnv/activate.md | 14 +- docs/cli/direnv/envrc.md | 8 - docs/cli/direnv/exec.md | 8 - docs/cli/doctor.md | 8 +- docs/cli/env.md | 37 +- docs/cli/exec.md | 43 +- docs/cli/generate.md | 9 + docs/cli/generate/git-pre-commit.md | 32 +- docs/cli/generate/github-action.md | 32 +- docs/cli/generate/task-docs.md | 43 +- docs/cli/global-flags.md | 32 - docs/cli/global.md | 52 - docs/cli/hook-env.md | 16 - docs/cli/hook-not-found.md | 17 - docs/cli/implode.md | 17 +- docs/cli/index.md | 2115 +---------------- docs/cli/install.md | 53 +- docs/cli/latest.md | 20 +- docs/cli/link.md | 30 +- docs/cli/local.md | 56 - docs/cli/ls-remote.md | 27 +- docs/cli/ls.md | 52 +- docs/cli/outdated.md | 44 +- docs/cli/plugins.md | 31 + docs/cli/plugins/install.md | 45 +- docs/cli/plugins/link.md | 31 +- docs/cli/plugins/ls-remote.md | 20 +- docs/cli/plugins/ls.md | 34 +- docs/cli/plugins/uninstall.md | 29 +- docs/cli/plugins/update.md | 30 +- docs/cli/prune.md | 30 +- docs/cli/registry.md | 6 +- docs/cli/render-help.md | 7 - docs/cli/render-mangen.md | 7 - docs/cli/reshim.md | 6 +- docs/cli/run.md | 77 +- docs/cli/self-update.md | 30 +- docs/cli/set.md | 31 +- docs/cli/settings.md | 16 + docs/cli/settings/get.md | 12 +- docs/cli/settings/ls.md | 14 +- docs/cli/settings/set.md | 21 +- docs/cli/settings/unset.md | 16 +- docs/cli/shell.md | 36 +- docs/cli/sync.md | 8 + docs/cli/sync/node.md | 28 +- docs/cli/sync/python.md | 18 +- docs/cli/tasks.md | 41 + docs/cli/tasks/deps.md | 29 +- docs/cli/tasks/edit.md | 24 +- docs/cli/tasks/info.md | 20 +- docs/cli/tasks/ls.md | 47 +- docs/cli/tasks/run.md | 89 +- docs/cli/trust.md | 33 +- docs/cli/uninstall.md | 33 +- docs/cli/unset.md | 27 +- docs/cli/upgrade.md | 74 +- docs/cli/usage.md | 8 +- docs/cli/use.md | 78 +- docs/cli/version.md | 6 +- docs/cli/watch.md | 48 +- docs/cli/where.md | 20 +- docs/cli/which.md | 32 +- mise.usage.kdl | 53 +- src/cli/alias/ls.rs | 4 +- src/cli/backends/ls.rs | 14 +- src/cli/current.rs | 1 + ...generate__task_docs__tests__task_docs.snap | 10 +- src/cli/generate/task_docs.rs | 40 +- src/cli/link.rs | 1 + src/cli/render_help.rs | 136 -- src/cli/tasks/info.rs | 4 + src/cli/tasks/ls.rs | 4 +- ..._tasks__info__tests__task_info_json-2.snap | 18 +- ...i__tasks__info__tests__task_info_json.snap | 28 +- src/cli/watch.rs | 17 +- src/config/mod.rs | 1 + src/task/mod.rs | 35 +- src/task/task_script_parser.rs | 61 +- tasks.md | 161 ++ 108 files changed, 1628 insertions(+), 3558 deletions(-) create mode 100644 docs/cli/alias.md delete mode 100644 docs/cli/asdf.md create mode 100644 docs/cli/backends.md create mode 100644 docs/cli/cache.md create mode 100644 docs/cli/config.md create mode 100644 docs/cli/direnv.md delete mode 100644 docs/cli/direnv/envrc.md delete mode 100644 docs/cli/direnv/exec.md create mode 100644 docs/cli/generate.md delete mode 100644 docs/cli/global-flags.md delete mode 100644 docs/cli/global.md delete mode 100644 docs/cli/hook-env.md delete mode 100644 docs/cli/hook-not-found.md delete mode 100644 docs/cli/local.md create mode 100644 docs/cli/plugins.md delete mode 100644 docs/cli/render-help.md delete mode 100644 docs/cli/render-mangen.md create mode 100644 docs/cli/settings.md create mode 100644 docs/cli/sync.md create mode 100644 docs/cli/tasks.md create mode 100644 tasks.md diff --git a/.markdownlintignore b/.markdownlintignore index 15454185b..d27042a96 100644 --- a/.markdownlintignore +++ b/.markdownlintignore @@ -1,6 +1,7 @@ -registry/ -target/ +/registry/ +/target/ CHANGELOG.md docs/node_modules/ node_modules/ test/ +/tasks.md diff --git a/.mise.toml b/.mise.toml index 51f1cee19..2d0a2e85e 100644 --- a/.mise.toml +++ b/.mise.toml @@ -23,6 +23,7 @@ direnv = "latest" actionlint = "latest" ripgrep = "latest" "pipx:toml-sort" = "latest" +usage = "latest" #python = { version = "latest", virtualenv = "{{env.HOME}}/.cache/venv" } #ruby = "3.1" @@ -49,7 +50,12 @@ run = "cargo build --color always --all-features" [tasks."render:usage"] depends = ["build"] env = { CLICOLOR_FORCE = "0" } -run = "mise usage > mise.usage.kdl" +run = [ + "mise usage > mise.usage.kdl", + "mise g task-docs > tasks.md", + "usage g md -f mise.usage.kdl -m --out-dir docs/cli --url-prefix /cli --html-encode", + "markdownlint --fix docs/cli", +] [tasks."render:completions"] depends = ["build", "render:usage"] diff --git a/.mise/tasks/filetask b/.mise/tasks/filetask index 36030a263..dda74f212 100755 --- a/.mise/tasks/filetask +++ b/.mise/tasks/filetask @@ -3,6 +3,7 @@ #USAGE flag "-f --force" help="Overwrite existing " #USAGE flag "-u --user " help="User to run as" #USAGE arg "" help="The file to write" default="file.txt" +#USAGE arg "" help="An arg with a default" default="mydefault" # mise description="This is a test build script" # mise depends=["lint", "build"] diff --git a/Cargo.lock b/Cargo.lock index 8d58204f7..6f747e073 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2575,9 +2575,9 @@ checksum = "953ec861398dccce10c670dfeaf3ec4911ca479e9c02154b3a215178c5f566f2" [[package]] name = "portable-atomic" -version = "1.8.0" +version = "1.9.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d30538d42559de6b034bc76fd6dd4c38961b1ee5c6c56e3808c50128fdbc22ce" +checksum = "cc9c68a3f6da06753e9335d63e27f6b9754dd1920d941135b7ea8224f141adb2" [[package]] name = "powerfmt" @@ -3611,9 +3611,9 @@ dependencies = [ [[package]] name = "tempfile" -version = "3.12.0" +version = "3.13.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "04cbcdd0c794ebb0d4cf35e88edd2f7d2c4c3e9a5a6dab322839b321c6a87a64" +checksum = "f0f2c9fc62d0beef6951ccffd757e241266a2c833136efbe35af6cd2567dca5b" dependencies = [ "cfg-if", "fastrand", @@ -4106,9 +4106,9 @@ checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da" [[package]] name = "usage-lib" -version = "0.8.0" +version = "0.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4d2f461138354b775e96629ce474dad0f7b9996dd902db85665de06b8a2aaeda" +checksum = "f1ea55fc767a5cbeffacb5740c9e68aea2a78109820bf6ff83fa1b76948ea637" dependencies = [ "clap", "heck 0.5.0", @@ -4118,6 +4118,7 @@ dependencies = [ "log", "miette", "once_cell", + "regex", "serde", "strum", "tera", diff --git a/Cargo.toml b/Cargo.toml index 292000dca..9c4b33b3d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -115,8 +115,8 @@ tokio = { version = "1.37.0", features = [ toml = { version = "0.8", features = ["parse"] } toml_edit = { version = "0.22", features = ["parse"] } url = "2.5.0" -#usage-lib = { path = "../usage/lib" } -usage-lib = { version = "0.8.0", features = ["clap", "docs"] } +# usage-lib = { path = "../usage/lib", features = ["clap", "docs"] } +usage-lib = { version = "0.8", features = ["clap", "docs"] } versions = { version = "6.2.0", features = ["serde"] } vfox = "0.1" walkdir = "2.5.0" diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index fbbfd81a3..041fd1f34 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,137 +1,133 @@ -import { defineConfig } from 'vitepress' -import { Command, commands } from './cli_commands' +import { defineConfig } from "vitepress"; +import { Command, commands } from "./cli_commands"; // https://vitepress.dev/reference/site-config export default defineConfig({ title: "mise-en-place", description: "mise-en-place documentation", - lang: 'en-US', + lang: "en-US", lastUpdated: true, - appearance: 'dark', + appearance: "dark", sitemap: { - hostname: 'https://mise.jdx.dev', + hostname: "https://mise.jdx.dev", }, themeConfig: { // https://vitepress.dev/reference/default-theme-config - outline: 'deep', + outline: "deep", nav: [ - {text: 'Dev Tools', link: '/dev-tools/'}, - {text: 'Environments', link: '/environments'}, - {text: 'Tasks', link: '/tasks/'}, + { 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: '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: 'Settings', link: '/settings'}, - {text: 'Plugins', link: '/plugins'}, - {text: 'Coming from rtx', link: '/rtx'}, - {text: 'Team', link: '/team'}, - {text: 'Contributing', link: '/contributing'}, - {text: 'Tips & Tricks', link: '/tips-and-tricks'}, + { text: "Getting Started", link: "/getting-started" }, + { text: "About", link: "/about" }, + { 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: "Settings", link: "/settings" }, + { text: "Plugins", link: "/plugins" }, + { text: "Coming from rtx", link: "/rtx" }, + { text: "Team", link: "/team" }, + { text: "Contributing", link: "/contributing" }, + { text: "Tips & Tricks", link: "/tips-and-tricks" }, { - text: 'Dev Tools', - link: '/dev-tools/', + 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: "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/', + 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: 'spm', link: '/dev-tools/backends/spm'}, - {text: 'ubi', link: '/dev-tools/backends/ubi'}, - {text: 'vfox', link: '/dev-tools/backends/vfox'}, - ] - } + { 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: "spm", link: "/dev-tools/backends/spm" }, + { text: "ubi", link: "/dev-tools/backends/ubi" }, + { text: "vfox", link: "/dev-tools/backends/vfox" }, + ], + }, ], }, { - text: 'Environments', - link: '/environments', + text: "Environments", + link: "/environments", items: [ - {text: 'direnv', link: '/direnv'}, - {text: 'Profiles', link: '/profiles'}, - {text: 'Templates', link: '/templates'}, + { text: "direnv", link: "/direnv" }, + { text: "Profiles", link: "/profiles" }, + { text: "Templates", link: "/templates" }, ], }, { - text: 'Tasks', - link: '/tasks/', + text: "Tasks", + link: "/tasks/", items: [ - {text: 'Running Tasks', link: '/tasks/running-tasks'}, - {text: 'File Tasks', link: '/tasks/file-tasks'}, - {text: 'TOML Tasks', link: '/tasks/toml-tasks'}, + { text: "Running Tasks", link: "/tasks/running-tasks" }, + { text: "File Tasks", link: "/tasks/file-tasks" }, + { text: "TOML Tasks", link: "/tasks/toml-tasks" }, ], }, { - text: 'Languages', + 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: "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', + text: "Internals", items: [ - {text: 'Cache Behavior', link: '/cache-behavior'}, - {text: 'Directory Structure', link: '/directories'}, - {text: 'Project Roadmap', link: '/project-roadmap'}, + { 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'}, - ...cliReference(commands), - ] + text: "CLI Reference", + link: "/cli/", + items: cliReference(commands), }, ], - socialLinks: [ - {icon: 'github', link: 'https://github.com/jdx/mise'} - ], + socialLinks: [{ icon: "github", link: "https://github.com/jdx/mise" }], editLink: { - pattern: 'https://github.com/jdx/mise/edit/main/docs/:path', + pattern: "https://github.com/jdx/mise/edit/main/docs/:path", }, search: { - provider: 'algolia', + provider: "algolia", options: { - indexName: 'rtx', - appId: '1452G4RPSJ', - apiKey: 'ad09b96a7d2a30eddc2771800da7a1cf', + indexName: "rtx", + appId: "1452G4RPSJ", + apiKey: "ad09b96a7d2a30eddc2771800da7a1cf", insights: true, - } + }, }, footer: { - message: 'Licensed under the MIT License. Maintained by @jdx and friends.', + message: + 'Licensed under the MIT License. Maintained by @jdx and friends.', copyright: 'Copyright © 2024 @jdx', }, carbonAds: { - code: 'CWYIPKQN', - placement: 'misejdxdev', + code: "CWYIPKQN", + placement: "misejdxdev", }, }, markdown: { @@ -141,19 +137,22 @@ export default defineConfig({ }, head: [ [ - 'script', - {async: '', src: 'https://www.googletagmanager.com/gtag/js?id=G-B69G389C8T'} + "script", + { + async: "", + src: "https://www.googletagmanager.com/gtag/js?id=G-B69G389C8T", + }, ], [ - 'script', + "script", {}, `window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); - gtag('config', 'G-B69G389C8T');` - ] + gtag('config', 'G-B69G389C8T');`, + ], ], -}) +}); function cliReference(commands: { [key: string]: Command }) { return Object.keys(commands) @@ -161,17 +160,21 @@ function cliReference(commands: { [key: string]: Command }) { .filter(([name, command]) => command.hide !== true) .map(([name, command]) => { const x: any = { - text: name, + text: `mise ${name}`, }; if (command.subcommands) { x.collapsed = true; - x.items = Object.keys(command.subcommands).map((subcommand) => ({ - text: subcommand, - link: `/cli/${name}/${subcommand}`, - })); + x.items = Object.keys(command.subcommands) + .filter( + (subcommand) => command.subcommands![subcommand].hide !== true, + ) + .map((subcommand) => ({ + text: `mise ${name} ${subcommand}`, + link: `/cli/${name}/${subcommand}`, + })); } else { x.link = `/cli/${name}`; } return x; - }) + }); } diff --git a/docs/cli/activate.md b/docs/cli/activate.md index 14dc6a07e..f0f186794 100644 --- a/docs/cli/activate.md +++ b/docs/cli/activate.md @@ -1,6 +1,5 @@ -## `mise activate [OPTIONS] [SHELL_TYPE]` +# `mise activate [args] [flags]` -```text Initializes mise in the current shell session This should go into your shell's rc file. @@ -22,27 +21,27 @@ specify the full path like this: Customize status output with `status` settings. -Usage: activate [OPTIONS] [SHELL_TYPE] +## Arguments -Arguments: - [SHELL_TYPE] - Shell type to generate the script for - - [possible values: bash, fish, nu, xonsh, zsh] +### `[SHELL_TYPE]` -Options: - --shims - Use shims instead of modifying PATH - Effectively the same as: - PATH="$HOME/.local/share/mise/shims:$PATH" +Shell type to generate the script for - -q, --quiet - Suppress non-error messages +## Flags + +### `--shims` + +Use shims instead of modifying PATH +Effectively the same as: + PATH="$HOME/.local/share/mise/shims:$PATH" + +### `-q --quiet` + +Suppress non-error messages Examples: - $ eval "$(mise activate bash)" - $ eval "$(mise activate zsh)" - $ mise activate fish | source - $ execx($(mise activate xonsh)) -``` + eval "$(mise activate bash)" + eval "$(mise activate zsh)" + mise activate fish | source + execx($(mise activate xonsh)) diff --git a/docs/cli/alias.md b/docs/cli/alias.md new file mode 100644 index 000000000..f2446f940 --- /dev/null +++ b/docs/cli/alias.md @@ -0,0 +1,20 @@ +# `mise alias [flags] [subcommand]` + +Manage aliases + +## Flags + +### `-p --plugin ` + +filter aliases by plugin + +### `--no-header` + +Don't show table header + +## Subcommands + +* [`mise alias get `](/cli/alias/get.md) +* [`mise alias ls [PLUGIN] [--no-header]`](/cli/alias/ls.md) +* [`mise alias set [args]`](/cli/alias/set.md) +* [`mise alias unset `](/cli/alias/unset.md) diff --git a/docs/cli/alias/get.md b/docs/cli/alias/get.md index ed9e95868..09c482223 100644 --- a/docs/cli/alias/get.md +++ b/docs/cli/alias/get.md @@ -1,20 +1,19 @@ -## `mise alias get ` +# `mise alias get ` -```text Show an alias for a plugin -This is the contents of an alias. entry in ~/.config/mise/config.toml +This is the contents of an alias.<PLUGIN> entry in ~/.config/mise/config.toml -Usage: alias get +## Arguments -Arguments: - - The plugin to show the alias for +### `` - - The alias to show +The plugin to show the alias for + +### `` + +The alias to show Examples: $ mise alias get node lts-hydrogen 20.0.0 -``` diff --git a/docs/cli/alias/ls.md b/docs/cli/alias/ls.md index 45eef411e..98d720495 100644 --- a/docs/cli/alias/ls.md +++ b/docs/cli/alias/ls.md @@ -1,29 +1,27 @@ -## `mise alias ls [OPTIONS] [PLUGIN]` +# `mise alias ls [PLUGIN] [--no-header]` -**Aliases:** `list` - -```text List aliases Shows the aliases that can be specified. These can come from user config or from plugins in `bin/list-aliases`. For user config, aliases are defined like the following in `~/.config/mise/config.toml`: - [alias.node] - lts = "20.0.0" + [alias.node] + lts = "20.0.0" + +## Arguments + +### `[PLUGIN]` + +Show aliases for <PLUGIN> -Usage: alias ls [OPTIONS] [PLUGIN] +## Flags -Arguments: - [PLUGIN] - Show aliases for +### `--no-header` -Options: - --no-header - Don't show table header +Don't show table header Examples: $ mise aliases node lts-hydrogen 20.0.0 -``` diff --git a/docs/cli/alias/set.md b/docs/cli/alias/set.md index c93ae52d4..8d34dcb2c 100644 --- a/docs/cli/alias/set.md +++ b/docs/cli/alias/set.md @@ -1,25 +1,23 @@ -## `mise alias set ` +# `mise alias set [args]` -**Aliases:** `add, create` - -```text Add/update an alias for a plugin This modifies the contents of ~/.config/mise/config.toml -Usage: alias set +## Arguments + +### `` + +The plugin to set the alias for + +### `` -Arguments: - - The plugin to set the alias for +The alias to set - - The alias to set +### `` - - The value to set the alias to +The value to set the alias to Examples: - $ mise alias set node lts-hydrogen 18.0.0 -``` + mise alias set node lts-hydrogen 18.0.0 diff --git a/docs/cli/alias/unset.md b/docs/cli/alias/unset.md index 6309acd96..e0a37287b 100644 --- a/docs/cli/alias/unset.md +++ b/docs/cli/alias/unset.md @@ -1,22 +1,19 @@ -## `mise alias unset ` +# `mise alias unset ` -**Aliases:** `del, delete, remove, rm` - -```text Clears an alias for a plugin This modifies the contents of ~/.config/mise/config.toml -Usage: alias unset +## Arguments + +### `` + +The plugin to remove the alias from -Arguments: - - The plugin to remove the alias from +### `` - - The alias to remove +The alias to remove Examples: - $ mise alias unset node lts-hydrogen -``` + mise alias unset node lts-hydrogen diff --git a/docs/cli/asdf.md b/docs/cli/asdf.md deleted file mode 100644 index 6511b7beb..000000000 --- a/docs/cli/asdf.md +++ /dev/null @@ -1,11 +0,0 @@ -## `mise asdf [ARGS]...` - -```text -[internal] simulates asdf for plugins that call "asdf" internally - -Usage: asdf [ARGS]... - -Arguments: - [ARGS]... - all arguments -``` diff --git a/docs/cli/backends.md b/docs/cli/backends.md new file mode 100644 index 000000000..990657f64 --- /dev/null +++ b/docs/cli/backends.md @@ -0,0 +1,7 @@ +# `mise backends [subcommand]` + +Manage backends + +## Subcommands + +* [`mise backends ls`](/cli/backends/ls.md) diff --git a/docs/cli/backends/ls.md b/docs/cli/backends/ls.md index bafac8558..8d1a9b537 100644 --- a/docs/cli/backends/ls.md +++ b/docs/cli/backends/ls.md @@ -1,19 +1,13 @@ -## `mise backends ls` +# `mise backends ls` -**Aliases:** `list` - -```text List built-in backends -Usage: backends ls - Examples: - $ mise backends ls - cargo - go - npm - pipx - spm - ubi -``` + $ mise backends ls + cargo + go + npm + pipx + spm + ubi diff --git a/docs/cli/bin-paths.md b/docs/cli/bin-paths.md index f69d81b4d..c38c16407 100644 --- a/docs/cli/bin-paths.md +++ b/docs/cli/bin-paths.md @@ -1,7 +1,3 @@ -## `mise bin-paths` +# `mise bin-paths` -```text List all the active runtime bin paths - -Usage: bin-paths -``` diff --git a/docs/cli/cache.md b/docs/cli/cache.md new file mode 100644 index 000000000..f38f6c724 --- /dev/null +++ b/docs/cli/cache.md @@ -0,0 +1,10 @@ +# `mise cache [subcommand]` + +Manage the mise cache + +Run `mise cache` with no args to view the current cache directory. + +## Subcommands + +* [`mise cache clear [PLUGIN]...`](/cli/cache/clear.md) +* [`mise cache prune [args] [flags]`](/cli/cache/prune.md) diff --git a/docs/cli/cache/clear.md b/docs/cli/cache/clear.md index 949d26ad0..ed518db46 100644 --- a/docs/cli/cache/clear.md +++ b/docs/cli/cache/clear.md @@ -1,13 +1,9 @@ -## `mise cache clear [PLUGIN]...` +# `mise cache clear [PLUGIN]...` -**Aliases:** `c` - -```text Deletes all cache files in mise -Usage: cache clear [PLUGIN]... +## Arguments + +### `[PLUGIN]...` -Arguments: - [PLUGIN]... - Plugin(s) to clear cache for e.g.: node, python -``` +Plugin(s) to clear cache for e.g.: node, python diff --git a/docs/cli/cache/prune.md b/docs/cli/cache/prune.md index d4ac12bf1..f2f761586 100644 --- a/docs/cli/cache/prune.md +++ b/docs/cli/cache/prune.md @@ -1,23 +1,22 @@ -## `mise cache prune [OPTIONS] [PLUGIN]...` +# `mise cache prune [args] [flags]` -**Aliases:** `p` - -```text Removes stale mise cache files By default, this command will remove files that have not been accessed in 30 days. Change this with the MISE_CACHE_PRUNE_AGE environment variable. -Usage: cache prune [OPTIONS] [PLUGIN]... +## Arguments + +### `[PLUGIN]...` + +Plugin(s) to clear cache for e.g.: node, python + +## Flags + +### `--dry-run` -Arguments: - [PLUGIN]... - Plugin(s) to clear cache for e.g.: node, python +Just show what would be pruned -Options: - --dry-run - Just show what would be pruned +### `-v --verbose...` - -v, --verbose... - Show pruned files -``` +Show pruned files diff --git a/docs/cli/completion.md b/docs/cli/completion.md index 8b226c14a..d79b76abf 100644 --- a/docs/cli/completion.md +++ b/docs/cli/completion.md @@ -1,19 +1,15 @@ -## `mise completion [SHELL]` +# `mise completion [args] [flags]` -```text Generate shell completions -Usage: completion [SHELL] +## Arguments -Arguments: - [SHELL] - Shell type to generate completions for - - [possible values: bash, fish, zsh] +### `[SHELL]` + +Shell type to generate completions for Examples: - $ mise completion bash > /etc/bash_completion.d/mise - $ mise completion zsh > /usr/local/share/zsh/site-functions/_mise - $ mise completion fish > ~/.config/fish/completions/mise.fish -``` + mise completion bash > /etc/bash_completion.d/mise + mise completion zsh > /usr/local/share/zsh/site-functions/_mise + mise completion fish > ~/.config/fish/completions/mise.fish diff --git a/docs/cli/config.md b/docs/cli/config.md new file mode 100644 index 000000000..567de82c7 --- /dev/null +++ b/docs/cli/config.md @@ -0,0 +1,16 @@ +# `mise config [flags] [subcommand]` + +Manage config files + +## Flags + +### `--no-header` + +Do not print table header + +## Subcommands + +* [`mise config generate [-o --output ]`](/cli/config/generate.md) +* [`mise config get [KEY] [-f --file ]`](/cli/config/get.md) +* [`mise config ls [--no-header]`](/cli/config/ls.md) +* [`mise config set [args] [flags]`](/cli/config/set.md) diff --git a/docs/cli/config/generate.md b/docs/cli/config/generate.md index ff6de0632..de08fd8cf 100644 --- a/docs/cli/config/generate.md +++ b/docs/cli/config/generate.md @@ -1,18 +1,14 @@ -## `mise config generate [OPTIONS]` +# `mise config generate [-o --output ]` -**Aliases:** `g` - -```text [experimental] Generate a mise.toml file -Usage: config generate [OPTIONS] +## Flags + +### `-o --output ` -Options: - -o, --output - Output to file instead of stdout +Output to file instead of stdout Examples: - $ mise cf generate > .mise.toml - $ mise cf generate --output=.mise.toml -``` + mise cf generate > .mise.toml + mise cf generate --output=.mise.toml diff --git a/docs/cli/config/get.md b/docs/cli/config/get.md index 4b7d8166a..4ed75d53e 100644 --- a/docs/cli/config/get.md +++ b/docs/cli/config/get.md @@ -1,22 +1,22 @@ -## `mise config get [OPTIONS] [KEY]` +# `mise config get [KEY] [-f --file ]` -```text Display the value of a setting in a mise.toml file -Usage: config get [OPTIONS] [KEY] +## Arguments -Arguments: - [KEY] - The path of the config to display +### `[KEY]` -Options: - -f, --file - The path to the mise.toml file to edit - - If not provided, the nearest mise.toml file will be used +The path of the config to display + +## Flags + +### `-f --file ` + +The path to the mise.toml file to edit + +If not provided, the nearest mise.toml file will be used Examples: $ mise toml get tools.python 3.12 -``` diff --git a/docs/cli/config/ls.md b/docs/cli/config/ls.md index acb08860d..db443b26f 100644 --- a/docs/cli/config/ls.md +++ b/docs/cli/config/ls.md @@ -1,15 +1,13 @@ -## `mise config ls [OPTIONS]` +# `mise config ls [--no-header]` -```text List config files currently in use -Usage: config ls [OPTIONS] +## Flags -Options: - --no-header - Do not print table header +### `--no-header` + +Do not print table header Examples: - $ mise config ls -``` + mise config ls diff --git a/docs/cli/config/set.md b/docs/cli/config/set.md index f0510d7f2..a2eb3bef6 100644 --- a/docs/cli/config/set.md +++ b/docs/cli/config/set.md @@ -1,30 +1,29 @@ -## `mise config set [OPTIONS] ` +# `mise config set [args] [flags]` -```text Display the value of a setting in a mise.toml file -Usage: config set [OPTIONS] +## Arguments -Arguments: - - The path of the config to display +### `` - - The value to set the key to +The path of the config to display -Options: - -f, --file - The path to the mise.toml file to edit - - If not provided, the nearest mise.toml file will be used +### `` - -t, --type - [default: string] - [possible values: string, integer, float, bool] +The value to set the key to + +## Flags + +### `-f --file ` + +The path to the mise.toml file to edit + +If not provided, the nearest mise.toml file will be used + +### `-t --type ` Examples: - $ mise config set tools.python 3.12 - $ mise config set settings.always_keep_download true - $ mise config set env.TEST_ENV_VAR ABC -``` + mise config set tools.python 3.12 + mise config set settings.always_keep_download true + mise config set env.TEST_ENV_VAR ABC diff --git a/docs/cli/current.md b/docs/cli/current.md index 0cce65425..6b32fa293 100644 --- a/docs/cli/current.md +++ b/docs/cli/current.md @@ -1,18 +1,18 @@ -## `mise current [PLUGIN]` +# `mise current [PLUGIN]` -```text Shows current active and installed runtime versions This is similar to `mise ls --current`, but this only shows the runtime and/or version. It's designed to fit into scripts more easily. -Usage: current [PLUGIN] +## Arguments -Arguments: - [PLUGIN] - Plugin to show versions of e.g.: ruby, node, cargo:eza, npm:prettier, etc +### `[PLUGIN]` + +Plugin to show versions of e.g.: ruby, node, cargo:eza, npm:prettier, etc Examples: + # outputs `.tool-versions` compatible format $ mise current python 3.11.0 3.10.0 @@ -26,4 +26,3 @@ Examples: # can output multiple versions $ mise current python 3.11.0 3.10.0 -``` diff --git a/docs/cli/deactivate.md b/docs/cli/deactivate.md index 93122d02a..d61d709a4 100644 --- a/docs/cli/deactivate.md +++ b/docs/cli/deactivate.md @@ -1,13 +1,9 @@ -## `mise deactivate` +# `mise deactivate` -```text Disable mise for current shell session This can be used to temporarily disable mise in a shell session. -Usage: deactivate - Examples: - $ mise deactivate -``` + mise deactivate diff --git a/docs/cli/direnv.md b/docs/cli/direnv.md new file mode 100644 index 000000000..0f46058fe --- /dev/null +++ b/docs/cli/direnv.md @@ -0,0 +1,13 @@ +# `mise direnv [subcommand]` + +Output direnv function to use mise inside direnv + +See for more information + +Because this generates the legacy files based on currently installed plugins, +you should run this command after installing new plugins. Otherwise +direnv may not know to update environment variables when legacy file versions change. + +## Subcommands + +* [`mise direnv activate`](/cli/direnv/activate.md) diff --git a/docs/cli/direnv/activate.md b/docs/cli/direnv/activate.md index 521ff928c..9bfc75c82 100644 --- a/docs/cli/direnv/activate.md +++ b/docs/cli/direnv/activate.md @@ -1,19 +1,15 @@ -## `mise direnv activate` +# `mise direnv activate` -```text Output direnv function to use mise inside direnv -See https://mise.jdx.dev/direnv.html for more information +See for more information Because this generates the legacy files based on currently installed plugins, you should run this command after installing new plugins. Otherwise direnv may not know to update environment variables when legacy file versions change. -Usage: direnv activate - Examples: - $ mise direnv activate > ~/.config/direnv/lib/use_mise.sh - $ echo 'use mise' > .envrc - $ direnv allow -``` + mise direnv activate > ~/.config/direnv/lib/use_mise.sh + echo 'use mise' > .envrc + direnv allow diff --git a/docs/cli/direnv/envrc.md b/docs/cli/direnv/envrc.md deleted file mode 100644 index 89cac882d..000000000 --- a/docs/cli/direnv/envrc.md +++ /dev/null @@ -1,8 +0,0 @@ -## `mise direnv envrc` - -```text -[internal] This is an internal command that writes an envrc file -for direnv to consume. - -Usage: direnv envrc -``` diff --git a/docs/cli/direnv/exec.md b/docs/cli/direnv/exec.md deleted file mode 100644 index 4a608daf9..000000000 --- a/docs/cli/direnv/exec.md +++ /dev/null @@ -1,8 +0,0 @@ -## `mise direnv exec` - -```text -[internal] This is an internal command that writes an envrc file -for direnv to consume. - -Usage: direnv exec -``` diff --git a/docs/cli/doctor.md b/docs/cli/doctor.md index b0931894f..6bdb722af 100644 --- a/docs/cli/doctor.md +++ b/docs/cli/doctor.md @@ -1,14 +1,8 @@ -## `mise doctor` +# `mise doctor` -**Aliases:** `dr` - -```text Check mise installation for possible problems -Usage: doctor - Examples: $ mise doctor [WARN] plugin node is not installed -``` diff --git a/docs/cli/env.md b/docs/cli/env.md index cbbd7aae6..32606c3e6 100644 --- a/docs/cli/env.md +++ b/docs/cli/env.md @@ -1,32 +1,29 @@ -## `mise env [OPTIONS] [TOOL@VERSION]...` +# `mise env [args] [flags]` -**Aliases:** `e` - -```text Exports env vars to activate mise a single time Use this if you don't want to permanently install mise. It's not necessary to use this if you have `mise activate` in your shell rc file. -Usage: env [OPTIONS] [TOOL@VERSION]... +## Arguments + +### `[TOOL@VERSION]...` + +Tool(s) to use + +## Flags + +### `-J --json` -Arguments: - [TOOL@VERSION]... - Tool(s) to use +Output in JSON format -Options: - -J, --json - Output in JSON format +### `-s --shell ` - -s, --shell - Shell type to generate environment variables for - - [possible values: bash, fish, nu, xonsh, zsh] +Shell type to generate environment variables for Examples: - $ eval "$(mise env -s bash)" - $ eval "$(mise env -s zsh)" - $ mise env -s fish | source - $ execx($(mise env -s xonsh)) -``` + eval "$(mise env -s bash)" + eval "$(mise env -s zsh)" + mise env -s fish | source + execx($(mise env -s xonsh)) diff --git a/docs/cli/exec.md b/docs/cli/exec.md index 4c9da75d0..2eee057a9 100644 --- a/docs/cli/exec.md +++ b/docs/cli/exec.md @@ -1,39 +1,39 @@ -## `mise exec [OPTIONS] [TOOL@VERSION]... [-- ...]` +# `mise exec [args] [flags]` -**Aliases:** `x` - -```text Execute a command with tool(s) set use this to avoid modifying the shell session or running ad-hoc commands with mise tools set. -Tools will be loaded from .mise.toml/.tool-versions, though they can be overridden with args +Tools will be loaded from .mise.toml/.tool-versions, though they can be overridden with <RUNTIME> args Note that only the plugin specified will be overridden, so if a `.tool-versions` file includes "node 20" but you run `mise exec python@3.11`; it will still load node@20. The "--" separates runtimes from the commands to pass along to the subprocess. -Usage: exec [OPTIONS] [TOOL@VERSION]... [-- ...] +## Arguments + +### `[TOOL@VERSION]...` + +Tool(s) to start e.g.: node@20 python@3.10 + +### `[COMMAND]...` + +Command string to execute (same as --command) + +## Flags + +### `-c --command ` -Arguments: - [TOOL@VERSION]... - Tool(s) to start e.g.: node@20 python@3.10 +Command string to execute - [COMMAND]... - Command string to execute (same as --command) +### `-j --jobs ` -Options: - -c, --command - Command string to execute +Number of jobs to run in parallel +[default: 4] - -j, --jobs - Number of jobs to run in parallel - [default: 4] - - [env: MISE_JOBS=] +### `--raw` - --raw - Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 +Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 Examples: @@ -45,4 +45,3 @@ Examples: # Run a command in a different directory: $ mise x -C /path/to/project node@20 -- node ./app.js -``` diff --git a/docs/cli/generate.md b/docs/cli/generate.md new file mode 100644 index 000000000..981299af4 --- /dev/null +++ b/docs/cli/generate.md @@ -0,0 +1,9 @@ +# `mise generate [subcommand]` + +[experimental] Generate files for various tools/services + +## Subcommands + +* [`mise generate git-pre-commit [flags]`](/cli/generate/git-pre-commit.md) +* [`mise generate github-action [flags]`](/cli/generate/github-action.md) +* [`mise generate task-docs [flags]`](/cli/generate/task-docs.md) diff --git a/docs/cli/generate/git-pre-commit.md b/docs/cli/generate/git-pre-commit.md index 10a547fff..a66da602e 100644 --- a/docs/cli/generate/git-pre-commit.md +++ b/docs/cli/generate/git-pre-commit.md @@ -1,31 +1,25 @@ -## `mise generate git-pre-commit [OPTIONS]` +# `mise generate git-pre-commit [flags]` -**Aliases:** `pre-commit` - -```text [experimental] Generate a git pre-commit hook This command generates a git pre-commit hook that runs a mise task like `mise run pre-commit` when you commit changes to your repository. -Usage: generate git-pre-commit [OPTIONS] +## Flags + +### `--hook ` + +Which hook to generate (saves to .git/hooks/$hook) + +### `-t --task ` -Options: - --hook - Which hook to generate (saves to .git/hooks/$hook) - - [default: pre-commit] +The task to run when the pre-commit hook is triggered - -t, --task - The task to run when the pre-commit hook is triggered - - [default: pre-commit] +### `-w --write` - -w, --write - write to .git/hooks/pre-commit and make it executable +write to .git/hooks/pre-commit and make it executable Examples: - $ mise generate git-pre-commit --write --task=pre-commit - $ git commit -m "feat: add new feature" # runs `mise run pre-commit` -``` + mise generate git-pre-commit --write --task=pre-commit + git commit -m "feat: add new feature" # runs `mise run pre-commit` diff --git a/docs/cli/generate/github-action.md b/docs/cli/generate/github-action.md index d06673fb8..bc6eb3d51 100644 --- a/docs/cli/generate/github-action.md +++ b/docs/cli/generate/github-action.md @@ -1,30 +1,26 @@ -## `mise generate github-action [OPTIONS]` +# `mise generate github-action [flags]` -```text [experimental] Generate a GitHub Action workflow file This command generates a GitHub Action workflow file that runs a mise task like `mise run ci` when you push changes to your repository. -Usage: generate github-action [OPTIONS] +## Flags -Options: - -n, --name - the name of the workflow to generate - - [default: ci] +### `-n --name ` - -t, --task - The task to run when the workflow is triggered - - [default: ci] +the name of the workflow to generate - -w, --write - write to .github/workflows/$name.yml +### `-t --task ` + +The task to run when the workflow is triggered + +### `-w --write` + +write to .github/workflows/$name.yml Examples: - $ mise generate github-action --write --task=ci - $ git commit -m "feat: add new feature" - $ git push # runs `mise run ci` on GitHub -``` + mise generate github-action --write --task=ci + git commit -m "feat: add new feature" + git push # runs `mise run ci` on GitHub diff --git a/docs/cli/generate/task-docs.md b/docs/cli/generate/task-docs.md index 7c41afda0..92dac9e26 100644 --- a/docs/cli/generate/task-docs.md +++ b/docs/cli/generate/task-docs.md @@ -1,28 +1,35 @@ -## `mise generate task-docs [OPTIONS]` +# `mise generate task-docs [flags]` -```text [experimental] Generate documentation for tasks in a project -Usage: generate task-docs [OPTIONS] +## Flags -Options: - -m, --multi - render each task as a separate document, requires `--output` to be a directory +### `-I --index` - -i, --inject - inserts the documentation into an existing file - - This will look for a special comment, , and replace it with the generated documentation. - It will replace everything between the comment and the next comment, so it can be - run multiple times on the same file to update the documentation. +write only an index of tasks, intended for use with `--multi` - -I, --index - write only an index of tasks, intended for use with `--multi` +### `-i --inject` - -o, --output - writes the generated docs to a file/directory +inserts the documentation into an existing file + +This will look for a special comment, <!-- mise-tasks -->, and replace it with the generated documentation. +It will replace everything between the comment and the next comment, <!-- /mise-tasks --> so it can be +run multiple times on the same file to update the documentation. + +### `-m --multi` + +render each task as a separate document, requires `--output` to be a directory + +### `-o --output ` + +writes the generated docs to a file/directory + +### `-r --root ` + +root directory to search for tasks + +### `-s --style