[#1671] Add documentation for pipx pin and unpin features

Expanded the README and examples documentation to describe the new 'pipx pin' and 'pipx unpin' commands, including usage details and example scenarios for pinning main and injected packages.

Author: JakeFloch

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
+```