Document the tool upgrade command (#5947)

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.
+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 upgrade black
+```
 
 To upgrade a single package in a tool environment:
 
 ```console
-$ uv tool install black --upgrade-package click
+$ uv tool upgrade black --upgrade-package click
 ```
 
-To upgrade all packages in a tool environment
+To reinstall all packages in a tool environment
 
 ```console
-$ uv tool install black --upgrade
+$ uv tool upgrade black --reinstall
 ```
 
 To reinstall a single package in a tool environment:
 
 ```console
-$ uv tool install black --reinstall-package click
+$ uv tool upgrade black --reinstall-package click
 ```
 
-To reinstall all packages in a tool environment
+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 --reinstall
+$ uv tool install black>=24
 ```
 
-All tool environment mutations will reinstall the tool executables, even if they have not changed.
+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
 

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