Merge branch 'main' into gh-1572-pipx-install-upgrade

Author: j-krl

docs/README.md

@@ -265,6 +265,18 @@ pipx inject ipython matplotlib pandas
 pipx inject ipython -r useful-packages.txt
 ```
 
+### Pin installed packages
+
+Use `pipx pin` when you need to hold an installation at its current version. Pinned packages are skipped by `pipx upgrade`, `pipx upgrade-all`, and `pipx reinstall`, so the environment keeps its existing app and dependency versions until you unpin it.
+
+- `pipx pin PACKAGE` pins the main package and any injected packages in that virtual environment.
+- `pipx pin PACKAGE --injected-only` leaves the main package upgradable but pins every injected package instead.
+- `pipx pin PACKAGE --skip PKG_A PKG_B` pins injected packages except the ones you list (the flag implies `--injected-only`).
+- `pipx unpin PACKAGE` re-enables upgrades for the package and anything that was pinned with it.
+- `pipx list --pinned` shows every pinned environment; add `--include-injected` to see pinned injected packages.
+
+pipx tracks the main package and any injected packages. It does not record individual transitive dependencies, so there is no way to pin a single dependency in isolation. Pinning the main package protects its dependency set because pipx skips running `pip install --upgrade` for that environment.
+
 ### Walkthrough: Running an Application in a Temporary Virtual Environment
 
 This is an alternative to `pipx install`.

docs/examples.md

@@ -187,3 +187,45 @@ This example pins `pip` (temporarily, until the next automatic upgrade, if that
 ```shell
 > pipx upgrade-shared --pip-args=pip==24.0
 ```
+
+## `pipx pin` examples
+
+Pinning keeps an installation at its current version until you call `pipx unpin`.
+
+Pin the entire environment (main package plus anything injected):
+
+```shell
+> pipx install httpie
+> pipx pin httpie
+> pipx list --pinned
+httpie <current version>
+```
+
+Pin only injected packages so the main package can continue to receive upgrades:
+
+```shell
+> pipx inject poetry poetry-plugin-export poetry-plugin-app
+> pipx pin poetry --injected-only
+Pinned 2 packages in venv poetry
+  - poetry-plugin-export <current version>
+  - poetry-plugin-app <current version>
+```
+
+Skip selected injected packages when pinning:
+
+```shell
+> pipx inject pdm pdm-django pdm-pytorch
+> pipx pin pdm --skip pdm-django
+Pinned 1 packages in venv pdm
+  - pdm-pytorch <current version>
+```
+
+Unpin everything so upgrades resume:
+
+```shell
+> pipx unpin poetry
+Unpinned 2 packages in venv poetry
+  - poetry
+  - poetry-plugin-export
+  - poetry-plugin-app
+```