From 7a0b610c19cccb231d3d32e6c8bd03bbaad4b372 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Fri, 9 Aug 2024 09:19:38 -0400
Subject: [PATCH] Document the `tool upgrade` command (#5947)

---
 docs/concepts/tools.md | 39 +++++++++++++++++++++++++++------------
 docs/guides/tools.md   | 24 ++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 12 deletions(-)

diff --git a/docs/concepts/tools.md b/docs/concepts/tools.md
index 29372b95b..cdc6a4226 100644
--- a/docs/concepts/tools.md
+++ b/docs/concepts/tools.md
@@ -40,33 +40,48 @@ Tool environments are placed in a directory with the same name as the tool packa
 Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to
 mutate a tool environment manually with a `pip` operation.
 
-Tool environments may be either mutated or re-created by subsequent `uv tool install` operations.
-
-To upgrade a single package in a tool environment:
-
-```console
-$ uv tool install black --upgrade-package click
-```
+Tool environments may be upgraded via `uv tool upgrade`, or re-created entirely via subsequent
+`uv tool install` operations.
 
 To upgrade all packages in a tool environment
 
 ```console
-$ uv tool install black --upgrade
+$ uv tool upgrade black
 ```
 
-To reinstall a single package in a tool environment:
+To upgrade a single package in a tool environment:
 
 ```console
-$ uv tool install black --reinstall-package click
+$ uv tool upgrade black --upgrade-package click
 ```
 
 To reinstall all packages in a tool environment
 
 ```console
-$ uv tool install black --reinstall
+$ uv tool upgrade black --reinstall
 ```
 
-All tool environment mutations will reinstall the tool executables, even if they have not changed.
+To reinstall a single package in a tool environment:
+
+```console
+$ uv tool upgrade black --reinstall-package click
+```
+
+Tool upgrades will respect the version constraints provided when installing the tool. For example,
+`uv tool install black >=23,<24` followed by `uv tool upgrade black` will upgrade Black to the
+latest version in the range `>=23,<24`.
+
+To instead replace the version constraints, re-install the tool with `uv tool install`:
+
+```console
+$ uv tool install black>=24
+```
+
+Similarly, tool upgrades will retain the settings provided when installing the tool. For example,
+`uv tool install black --prelease allow` followed by `uv tool upgrade black` will retain the
+`--prelease allow` setting.
+
+Tool upgrades will reinstall the tool executables, even if they have not changed.
 
 ### Including additional dependencies
 
diff --git a/docs/guides/tools.md b/docs/guides/tools.md
index a8caad0f5..d962628ea 100644
--- a/docs/guides/tools.md
+++ b/docs/guides/tools.md
@@ -151,6 +151,30 @@ As with `uvx`, installations can include additional packages:
 $ uv tool install mkdocs --with mkdocs-material
 ```
 
+## Upgrading tools
+
+To upgrade a tool, use `uv tool upgrade`:
+
+```console
+$ uv tool upgrade ruff
+```
+
+Tool upgrades will respect the version constraints provided when installing the tool. For example,
+`uv tool install ruff >=0.3,<0.4` followed by `uv tool upgrade ruff` will upgrade Ruff to the latest
+version in the range `>=0.3,<0.4`.
+
+To instead replace the version constraints, re-install the tool with `uv tool install`:
+
+```console
+$ uv tool install ruff>=0.4
+```
+
+To instead upgrade all tools:
+
+```console
+$ uv tool upgrade --all
+```
+
 ## Next steps
 
 To learn more about managing tools with uv, see the [Tools concept](../concepts/tools.md) page and