Skip to content

Commit

Permalink
Revert "docs: set prose-wrap with prettier (#4038)"
Browse files Browse the repository at this point in the history
This reverts commit 2fba8b0.
  • Loading branch information
jdx committed Jan 10, 2025
1 parent 86b5816 commit 065dd8f
Show file tree
Hide file tree
Showing 73 changed files with 1,860 additions and 1,590 deletions.
3 changes: 1 addition & 2 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,4 @@ blank_issues_enabled: false
contact_links:
- name: Features, Bug Reports, Questions
url: https://github.com/jdx/mise/discussions/new/choose
about: Our preferred starting point if you have any questions or suggestions
about configuration, features or behavior.
about: Our preferred starting point if you have any questions or suggestions about configuration, features or behavior.
4 changes: 2 additions & 2 deletions .idea/codeStyles/codeStyleConfig.xml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 0 additions & 3 deletions .prettierrc.toml

This file was deleted.

15 changes: 6 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,15 @@

## What is it?

- Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm) or [pyenv](https://github.com/pyenv/pyenv)
but for any language) it manages [dev tools](https://mise.jdx.dev/dev-tools/) like node, python, cmake, terraform, and
[hundreds more](https://mise.jdx.dev/registry.html).
- Like [direnv](https://github.com/direnv/direnv) it manages [environment variables](https://mise.jdx.dev/environments/)
for different project directories.
- Like [make](https://www.gnu.org/software/make/manual/make.html) it manages [tasks](https://mise.jdx.dev/tasks/) used
to build and test projects.
- Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm) or [pyenv](https://github.com/pyenv/pyenv) but for any language) it manages [dev tools](https://mise.jdx.dev/dev-tools/) like node, python, cmake, terraform, and [hundreds more](https://mise.jdx.dev/registry.html).
- Like [direnv](https://github.com/direnv/direnv) it manages [environment variables](https://mise.jdx.dev/environments/) for different project directories.
- Like [make](https://www.gnu.org/software/make/manual/make.html) it manages [tasks](https://mise.jdx.dev/tasks/) used to build and test projects.

## 30 Second Demo

The following shows using mise to install different versions of [node](https://nodejs.org). Note that calling
`which node` gives us a real path to node, not a shim.
The following shows using mise to install different versions
of [node](https://nodejs.org).
Note that calling `which node` gives us a real path to node, not a shim.

[![demo](./docs/demo.gif)](./docs/demo.gif)

Expand Down
73 changes: 37 additions & 36 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,63 +7,63 @@ Please open a ticket or send me an email if you have thoughts on how mise can be

## Core CLI Security

Development of the "core CLI" is done on jdx/mise which only a single developer (me, @jdx) has access to. Other
contributors may only submit contributions via public Pull Requests. Reducing the number of developers with access down
to 1 minimizes the chance of keys being leaked.
Development of the "core CLI" is done on jdx/mise which only a single developer (me, @jdx) has access to.
Other contributors may only submit contributions via public Pull Requests. Reducing the number
of developers with access down to 1 minimizes the chance of keys being leaked.

This does create a [bus factor](https://en.wikipedia.org/wiki/Bus_factor) problem. If I suddenly died one day or
otherwise wasn't able to continue development at all there are some successors listed in my GitHub account that can take
over my account if need be.
This does create a [bus factor](https://en.wikipedia.org/wiki/Bus_factor) problem. If I suddenly died one day
or otherwise wasn't able to continue development at all there are some successors listed in my GitHub account
that can take over my account if need be.

The dependencies in the core CLI are a security vector. I've tried to be judicious about what dependencies make it into
the project. I only select dependencies with broad usage across the Rust community where possible. I'm open to PRs or
suggestions on reducing dependency count even at the cost of functionality because it will make mise more secure.
the project. I only select dependencies with broad usage across the Rust community where possible.
I'm open to PRs or suggestions on reducing dependency count even at the cost of functionality because it will make
mise more secure.

## mise.jdx.dev

mise.jdx.dev is the asset host for mise. It's used to host precompiled mise CLI binaries, and hosts a
"[VERSION](https://mise.jdx.dev/VERSION)" which mise uses to occasionally check for a new version being released.
Everything hosted there uses a single vendor to reduce surface area.
mise.jdx.dev is the asset host for mise. It's used to host precompiled mise CLI binaries, and hosts a "[VERSION](https://mise.jdx.dev/VERSION)"
which mise uses to occasionally check for a new version being released. Everything hosted there uses a single
vendor to reduce surface area.

## Cosign and slsa verification

mise will verify signatures of tools using [cosign](https://docs.sigstore.dev/) and
[slsa-verifier](https://github.com/slsa-framework/slsa-verifier) if cosign/slsa-verifier is installed and the tool is
configured to support it. Typically, these will be tools using aqua as the backend. See the
[aqua docs](https://aquaproj.github.io/docs/reference/security/cosign-slsa) for more on how this is configured in the
[aqua registry](https://github.com/aquaproj/aqua-registry).
mise will verify signatures of tools using [cosign](https://docs.sigstore.dev/) and [slsa-verifier](https://github.com/slsa-framework/slsa-verifier)
if cosign/slsa-verifier is installed and the tool is configured to support it. Typically, these will be tools using aqua as the backend.
See the [aqua docs](https://aquaproj.github.io/docs/reference/security/cosign-slsa) for more on how this is
configured in the [aqua registry](https://github.com/aquaproj/aqua-registry).

You will see this verification happen when tools are installed, setting `--verbose` when installing tools will help make
it easier to see if verification happened. If you happen to notice a tool offers gpg/slsa/cosign/minisign/etc, see if
you can make a PR to the aqua registry for mise to pick it up.
You will see this verification happen when tools are installed, setting `--verbose` when installing tools will help
make it easier to see if verification happened. If you happen to notice a tool offers gpg/slsa/cosign/minisign/etc, see if you can
make a PR to the aqua registry for mise to pick it up.

## `mise.lock`

mise has support for [lockfiles](https://mise.jdx.dev/configuration/settings.html#lockfile) which will store/verify the
checksum of tool tarballs. Committing this into your repository is a good way to ensure that the exact same version of a
tool is installed across all developers and CI/CD systems.
mise has support for [lockfiles](https://mise.jdx.dev/configuration/settings.html#lockfile) which will
store/verify the checksum of tool tarballs. Committing this into your repository is a good way to ensure
that the exact same version of a tool is installed across all developers and CI/CD systems.

Not all backends support this—notably asdf plugins do not.

## asdf plugins

asdf plugins in asdf (but not with mise's default tools) are dangerous. They are typically owned by random developers
unconnected to either asdf or the tool vendor. They may get hacked or maliciously inject code into their plugin that
could trivially execute code on your machine.
unconnected to either asdf or the tool vendor. They may get hacked or maliciously inject code into
their plugin that could trivially execute code on your machine.

asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry.toml) whenever
possible. Sometimes it is not possible to use more secure backends like aqua/ubi because tools have complex install
setups or need to export env vars. As of 2025-01-08, <25% of tools use asdf plugins as the default backend. All of these
are hosted in the [mise-plugins org](https://github.com/mise-plugins) to secure the supply chain so you do not need to
rely on plugins maintained by anyone except me.
asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry.toml) whenever possible.
Sometimes it is not possible to use more secure backends like aqua/ubi because tools have complex install
setups or need to export env vars. As of 2025-01-08, <25% of tools use asdf plugins as the default backend.
All of these are hosted in the [mise-plugins org](https://github.com/mise-plugins) to secure the supply
chain so you do not need to rely on plugins maintained by anyone except me.

Of course if you _manually_ add plugins not from the mise-plugins org you will want to ensure they are coming from a
trusted source.
Of course if you _manually_ add plugins not from the mise-plugins org you will want to ensure they
are coming from a trusted source.

Please contribute to this effort to migrate away from asdf plugins by checking if a tool works in ubi or aqua and
submitting a PR to [registry.toml](https://github.com/jdx/mise/blob/main/registry.toml) to add it. If it doesn't work in
ubi or is missing from aqua, submit an issue or PR to the respective project to add it. New tools using asdf are **not**
likely to be accepted unless they cannot be supported with any other backend.
Please contribute to this effort to migrate away from asdf plugins by checking if a tool works in ubi or aqua and submitting a PR to
[registry.toml](https://github.com/jdx/mise/blob/main/registry.toml) to add it. If it doesn't work
in ubi or is missing from aqua, submit an issue or PR to the respective project to add it. New tools
using asdf are **not** likely to be accepted unless they cannot be supported with any other backend.

## Supported Versions

Expand Down Expand Up @@ -138,7 +138,8 @@ MFPobhR7zlCShd7TdY1a41uxTGB+Wmn4DO0s/wzSgdgxIzG+TM1X47owe7l5RiI1

## Release gpg key

This is the gpg key used to sign deb releases and the SHASUMS files contained within releases.
This is the gpg key used to sign deb releases and the SHASUMS files
contained within releases.

<details>
<summary>Release gpg key</summary>
Expand Down
3 changes: 1 addition & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
# mise-docs

This repository contains the documentation website for the runtime executor [mise](https://github.com/jdx/mise). The
website is powered by [VitePress](https://vitepress.dev/).
This repository contains the documentation website for the runtime executor [mise](https://github.com/jdx/mise). The website is powered by [VitePress](https://vitepress.dev/).
54 changes: 31 additions & 23 deletions docs/about.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,42 @@
# About

`mise` (pronounced "meez") or "mise-en-place" is a development environment setup tool. The name refers to a French
culinary phrase that roughly translates to "setup" or "put in place". The idea is that before one begins cooking, they
should have all their utensils and ingredients ready to go in their place.
`mise` (pronounced "meez") or "mise-en-place" is a development environment setup tool.
The name refers to a French culinary phrase that roughly translates to "setup" or "put in place".
The idea is that before one begins cooking, they should have all their utensils and ingredients
ready to go in their place.

`mise` does the same for your projects. Using its `mise.toml` config file, you'll have a consistent way to setup and
interact with your projects no matter what language they're written in.
`mise` does the same for your projects. Using its `mise.toml` config file,
you'll have a consistent way to setup and interact with your projects no matter what
language they're written in.

Its functionality is grouped into 3 categories described below.

`mise` installs and manages dev tools/runtimes like node, python, or terraform both simplifying installing these tools
and allowing you to specify which version of these tools to use in different projects. `mise` supports
[hundreds](/plugins.md) of dev tools.
`mise` installs and manages dev tools/runtimes like node, python, or terraform both
simplifying installing these tools and allowing you to specify which version of these
tools to use in different projects. `mise` supports [hundreds](/plugins.md) of dev tools.

`mise` manages environment variables letting you specify configuration like `AWS_ACCESS_KEY_ID` that may differ between
projects. It can also be used to automatically activate a [Python virtualenv](/lang/python) when entering projects too.
`mise` manages environment variables letting you specify configuration like
`AWS_ACCESS_KEY_ID` that may differ between projects. It can also be used to
automatically activate a [Python virtualenv](/lang/python) when entering projects too.

`mise` is a task runner that can be used to share common tasks within a project among developers and make things like
running tasks on file changes easy.
`mise` is a task runner that can be used to share common tasks within
a project among developers and make things like running tasks on file changes
easy.

## Contact

`mise` is mostly built and maintained by me, [Jeff Dickey](https://jdx.dev). The goal is to make local development of
software easy and consistent across languages. I have spent many years building dev tools and thinking about the
problems that `mise` addresses.

I try to use the first-person in these docs since the reality is it's generally me writing them and I think it makes it
more interesting having a bit of my personality in the text.

This project is simply a labor of love. I am making it because I want to make your life as a developer easier. I hope
you find it useful. Feedback is a massive driver for me. If you have anything positive or negative to say-even if it's
just to say hi-please reach out to me either on [Twitter](https://twitter.com/jdxcode),
[Mastodon](https://fosstodon.org/@jdx), [Discord](https://discord.gg/UBa7pJUN7Z), or `jdx at this domain`.
`mise` is mostly built and maintained by me, [Jeff Dickey](https://jdx.dev). The goal is
to make local development of software easy and consistent across languages. I
have spent many years building dev tools and thinking about the problems that `mise`
addresses.

I try to use the first-person in these docs since the reality is it's generally me
writing them and I think it makes it more interesting having a bit of my personality
in the text.

This project is simply a labor of love. I am making it because I want to make
your life as a developer easier. I hope you find it useful. Feedback is a massive
driver for me. If you have anything positive or negative to say-even if it's just
to say hi-please reach out to me either on [Twitter](https://twitter.com/jdxcode),
[Mastodon](https://fosstodon.org/@jdx), [Discord](https://discord.gg/UBa7pJUN7Z),
or `jdx at this domain`.
33 changes: 18 additions & 15 deletions docs/cache-behavior.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,31 @@
# Cache Behavior

mise makes use of caching in many places in order to be efficient. The details about how long to keep cache for should
eventually all be configurable. There may be gaps in the current behavior where things are hardcoded, but I'm happy to
add more settings to cover whatever config is needed.
mise makes use of caching in many places in order to be efficient. The details about how long to keep
cache for should eventually all be configurable. There may be gaps in the current behavior where
things are hardcoded, but I'm happy to add more settings to cover whatever config is needed.

Below I explain the behavior it uses around caching. If you're seeing behavior where things don't appear to be updating,
this is a good place to start.
Below I explain the behavior it uses around caching. If you're seeing behavior where things don't appear
to be updating, this is a good place to start.

## Plugin/Runtime Cache

Each plugin has a cache that's stored in `~/$MISE_CACHE_DIR/<PLUGIN>`. It stores the list of versions available for that
plugin (`mise ls-remote <PLUGIN>`), the idiomatic filenames (see below), the list of aliases, the bin directories within
each runtime installation, and the result of running `exec-env` after the runtime was installed.
Each plugin has a cache that's stored in `~/$MISE_CACHE_DIR/<PLUGIN>`. It stores
the list of versions available for that plugin (`mise ls-remote <PLUGIN>`), the idiomatic filenames (see below),
the list of aliases, the bin directories within each runtime installation, and the result of
running `exec-env` after the runtime was installed.

Remote versions are updated daily by default. The file is zlib messagepack, if you want to view it you can run the
following (requires [msgpack-cli](https://github.com/msgpack/msgpack-cli)).
Remote versions are updated daily by default. The file is zlib messagepack, if you want to view it you can
run the following (requires [msgpack-cli](https://github.com/msgpack/msgpack-cli)).

```sh
cat ~/$MISE_CACHE_DIR/node/remote_versions.msgpack.z | perl -e 'use Compress::Raw::Zlib;my $d=new Compress::Raw::Zlib::Inflate();my $o;undef $/;$d->inflate(<>,$o);print $o;' | msgpack-cli decode
```

Note that the caching of `exec-env` may be problematic if the script isn't simply exporting static values. The vast
majority of `exec-env` scripts only export static values, but if you're working with a plugin that has a dynamic
`exec-env` submit a ticket and we can try to figure out what to do.
Note that the caching of `exec-env` may be problematic if the script isn't simply exporting
static values. The vast majority of `exec-env` scripts only export static values, but if you're
working with a plugin that has a dynamic `exec-env` submit
a ticket and we can try to figure out what to do.

Caching `exec-env` massively improved the performance of mise since it requires calling bash every time mise is
initialized. Ideally, we can keep this behavior.
Caching `exec-env` massively improved the performance of mise since it requires calling bash
every time mise is initialized. Ideally, we can keep this
behavior.
Loading

0 comments on commit 065dd8f

Please sign in to comment.