docs(pip_freeze): clarify --all; add concise example

[CortexShadow]

Summary
Improves the documentation for pip freeze --all by adding a clear explanatory note and a before/after example. This is a documentation-only change; no behavior is modified.

Motivation
The current description of --all can be misread and leaves ambiguity about which packages are shown. By making it explicit that pip, setuptools, and wheel are skipped by default—and included with --all—the docs now provide a more accurate and practical mental model for users.

Changes

• Added a .. note:: clarifying default behavior and the effect of --all.
• Introduced Unix and Windows examples comparing pip freeze vs. pip freeze --all.
• Kept the style consistent with the CLI reference page.

Notes

• Local linters, pre-commit hooks, targeted freeze tests, and the Sphinx docs build all pass.
• No changelog/news entry is required since this is docs-only.

Related
Closes #13557

[notatallshaw]

Hi @CoretexShadow thanks for submitting this PR to pip!

All pip maintainers currently operate on a volunteer basis, so it can take some time for one of to take a look and review a PR. I will try and make some time soon to review this PR though.

[sepehr-rs]

Hi @CortexShadow, thanks a lot for contributing to pip!
I’m not on the triage team yet, so I can’t formally approve, but I checked the updated docs and they’re consistent with pip’s behavior. This looks good to me!

[CortexShadow]

Hi @CortexShadow, thanks a lot for contributing to pip! I’m not on the triage team yet, so I can’t formally approve, but I checked the updated docs and they’re consistent with pip’s behavior. This looks good to me!

Thanks for checking this and confirming! Really appreciate your feedback.

[ichard26]

Hi, thanks for your interest in improving pip!

While I agree we could document pip freeze --all better, we can probably simplify how we go about that. It's likely a very uncommon option. Short and sweet is best.

Sorry for the long wait!

[ichard26]

Suggested change

	.. note::
	By default, ``pip freeze`` omits some bootstrap tooling so the output focuses on
	your project’s dependencies. In Python **3.11 and earlier**, this means ``pip``,
	``setuptools`` and ``wheel`` are skipped by default; in Python **3.12 and later**,
	only ``pip`` is skipped. Use ``--all`` to include those entries as well when you
	need a complete environment snapshot. Note that ``pip freeze`` reports what is
	installed—it does **not** compute a lockfile or a solver result.
	.. note::
	By default, ``pip freeze`` omits some bootstrap tooling so the output focuses on
	your project’s dependencies. On Python **3.11 and earlier**, this means ``pip``,
	``setuptools`` and ``wheel`` are skipped by default; on Python **3.12 and later**,
	only ``pip`` is skipped. Use ``--all`` to include those packages as well when you
	need a complete environment snapshot. Note that ``pip freeze`` reports what is
	installed—it does **not** compute a lockfile or a solver result.

[ichard26]

Also, on Python 3.11 and lower, distribute is also ignored.

[ichard26]

To be honest, I don't think we gain much from including an example. It's predictable what --all will do given the note you added earlier. I suspect --all is very rarely used, so IMO it doesn't warrant an example.

[ichard26]

I think this would be more useful if it was moved up to be at the end of the "Description" section

[ichard26]

We should really make this clearer in the contributing docs, but we only add changelog entries for documentation changes when the changes are major (like restructuring a large portion).

[CortexShadow]

We should really make this clearer in the contributing docs, but we only add changelog entries for documentation changes when the changes are major (like restructuring a large portion).

Thanks for the review! I’ve applied the requested changes, and I agree that no changelog entry is needed for these minor documentation updates. I’ve removed the unnecessary example, clarified the --all option, and moved the note as suggested.

[ichard26]

Thank you!