diff --git a/docs/html/cli/index.md b/docs/html/cli/index.md index a3aef3b10ba..57b15e59525 100644 --- a/docs/html/cli/index.md +++ b/docs/html/cli/index.md @@ -30,6 +30,13 @@ pip_check pip_lock ``` +```{toctree} +:maxdepth: 1 +:caption: Command-line usability and shell integration + +pip_completion +``` + ```{toctree} :maxdepth: 1 :caption: Handling Distribution Files diff --git a/docs/html/cli/pip_completion.rst b/docs/html/cli/pip_completion.rst new file mode 100644 index 00000000000..3476db3b70e --- /dev/null +++ b/docs/html/cli/pip_completion.rst @@ -0,0 +1,72 @@ +.. _`pip completion`: + +============== +pip completion +============== + + +Usage +===== + +.. tab:: Unix/macOS + + .. pip-command-usage:: completion "python -m pip" + +.. tab:: Windows + + .. pip-command-usage:: completion "py -m pip" + + +Description +=========== + +.. pip-command-description:: completion + +Options +======= + +.. pip-command-options:: completion + + +Example Setups +============== + +Enable pip tab completion in your shell: + +.. tab:: Bash + + Add the following line to your ~/.bashrc: + + .. code-block:: console + + echo 'eval "$(python -m pip completion --bash)"' >> ~/.bashrc + + Then reload your shell or run ``source ~/.bashrc`` to enable it immediately. + +.. tab:: Zsh + + Add the following line to your ~/.zshrc: + + .. code-block:: console + + echo 'eval "$(python -m pip completion --zsh)"' >> ~/.zshrc + + Reload your shell or run ``source ~/.zshrc``. + +.. tab:: PowerShell + + Add the following line to your PowerShell profile: + + .. code-block:: powershell + + python -m pip completion --powershell | Out-String | Invoke-Expression + + Restart your PowerShell session for the changes to take effect. + + .. note:: + + On Windows, ``pip.exe`` may point to a specific Python installation + (e.g. ``C:\Users\\AppData\Local\Programs\Python\Python313\python.exe -m pip``). + In this case, tab completion works for that exact command. To enable + completion for the ``pip`` command itself in PowerShell, you can use + ``Register-ArgumentCompleter`` with ``CommandName pip``. diff --git a/news/13536.doc.rst b/news/13536.doc.rst new file mode 100644 index 00000000000..c8e25d1ad14 --- /dev/null +++ b/news/13536.doc.rst @@ -0,0 +1 @@ +Add ``pip completion`` documentation. diff --git a/src/pip/_internal/commands/completion.py b/src/pip/_internal/commands/completion.py index 6d9597bdea0..28edb20cd3d 100644 --- a/src/pip/_internal/commands/completion.py +++ b/src/pip/_internal/commands/completion.py @@ -81,6 +81,8 @@ class CompletionCommand(Command): """A helper command to be used for command completion.""" ignore_require_venv = True + usage = """ + %prog [options]""" def add_options(self) -> None: self.cmd_opts.add_option(