From 5708bc7a8f5b70bc955cd0669fb0804eb92258f7 Mon Sep 17 00:00:00 2001
From: Zander Hill <zander@xargs.io>
Date: Tue, 23 Apr 2024 04:13:47 -0700
Subject: [PATCH] Add docs for pipx and ubi backends (#54)

---
 .vitepress/config.ts        |  2 ++
 dev-tools/backends/index.md |  2 ++
 dev-tools/backends/pipx.md  | 53 +++++++++++++++++++++++++++++++++++++
 dev-tools/backends/ubi.md   | 42 +++++++++++++++++++++++++++++
 4 files changed, 99 insertions(+)
 create mode 100644 dev-tools/backends/pipx.md
 create mode 100644 dev-tools/backends/ubi.md

diff --git a/.vitepress/config.ts b/.vitepress/config.ts
index cca5b69..5c6fa2b 100644
--- a/.vitepress/config.ts
+++ b/.vitepress/config.ts
@@ -48,6 +48,8 @@ export default defineConfig({
               { 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' },
             ]
           }
         ],
diff --git a/dev-tools/backends/index.md b/dev-tools/backends/index.md
index f8818b7..cc649fd 100644
--- a/dev-tools/backends/index.md
+++ b/dev-tools/backends/index.md
@@ -6,6 +6,8 @@ In addition to asdf plugins, you can also directly install CLIs with some packag
 * [Cargo](/dev-tools/backends/cargo) <Badge type="warning" text="experimental" />
 * [Go](/dev-tools/backends/go) <Badge type="warning" text="experimental" />
 * [NPM](/dev-tools/backends/npm) <Badge type="warning" text="experimental" />
+* [Pipx](/dev-tools/backends/pipx) <Badge type="warning" text="experimental" />
+* [Ubi](/dev-tools/backends/ubi) <Badge type="warning" text="experimental" />
 * [More coming soon!](https://github.com/jdx/mise/discussions/1250)
 
 ::: tip
diff --git a/dev-tools/backends/pipx.md b/dev-tools/backends/pipx.md
new file mode 100644
index 0000000..59932ed
--- /dev/null
+++ b/dev-tools/backends/pipx.md
@@ -0,0 +1,53 @@
+# pipx Backend <Badge type="warning" text="experimental" />
+
+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/dev-tools/backends/ubi.md b/dev-tools/backends/ubi.md
new file mode 100644
index 0000000..581e458
--- /dev/null
+++ b/dev-tools/backends/ubi.md
@@ -0,0 +1,42 @@
+# Ubi Backend <Badge type="warning" text="experimental" />
+
+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.