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..6131811a45b --- /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 + +Examples +======== + +Enable bash completion: + +.. code-block:: console + + $ python -m pip completion --bash + # pip bash completion start + _pip_completion() + { + COMPREPLY=( $( COMP_WORDS="${COMP_WORDS[*]}" \ + COMP_CWORD=$COMP_CWORD \ + PIP_AUTO_COMPLETE=1 $1 2>/dev/null ) ) + } + complete -o default -F _pip_completion /usr/bin/python -m pip + # pip bash completion end + +Enable PowerShell completion: + +.. code-block:: console + + > py -m pip completion --powershell + if ((Test-Path Function:\\TabExpansion) -and -not ` + (Test-Path Function:\\_pip_completeBackup)) {{ + Rename-Item Function:\\TabExpansion _pip_completeBackup + }} + function TabExpansion($line, $lastWord) {{ + $lastBlock = [regex]::Split($line, '[|;]')[-1].TrimStart() + if ($lastBlock.StartsWith("{prog} ")) {{ + $Env:COMP_WORDS=$lastBlock + $Env:COMP_CWORD=$lastBlock.Split().Length - 1 + $Env:PIP_AUTO_COMPLETE=1 + (& {prog}).Split() + Remove-Item Env:COMP_WORDS + Remove-Item Env:COMP_CWORD + Remove-Item Env:PIP_AUTO_COMPLETE + }} + elseif (Test-Path Function:\\_pip_completeBackup) {{ + # Fall back on existing tab expansion + _pip_completeBackup $line $lastWord + }} + }} 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(