From cc04a993d8f46b4e98d6909eb5170430274e6256 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Bidoul?= Date: Wed, 28 Dec 2022 12:13:16 +0100 Subject: [PATCH] Clarify the role of the egg URL fragment --- docs/html/topics/vcs-support.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/html/topics/vcs-support.md b/docs/html/topics/vcs-support.md index 70bb5beb9dc..d696de5ea08 100644 --- a/docs/html/topics/vcs-support.md +++ b/docs/html/topics/vcs-support.md @@ -136,12 +136,13 @@ option. ## URL fragments -pip looks at 2 fragments for VCS URLs: +pip looks at the `subdirectory` fragments for VCS URLs for specifying the path to the +Python package, when it is not in the root of the VCS directory. eg: `pkg_dir`. -- `egg`: For specifying the "project name" for use in pip's dependency - resolution logic. eg: `egg=project_name` -- `subdirectory`: For specifying the path to the Python package, when it is not - in the root of the VCS directory. eg: `pkg_dir` +pip also looks at the `egg` fragment specifying the "project name". In practice the +`egg` fragment is only required to help pip determine the VCS clone location in editable +mode. In all other circumstance the `egg` fragment is not necessary and its use is +discouraged. ````{admonition} Example If your repository layout is: @@ -157,6 +158,12 @@ some_other_file Then, to install from this repository, the syntax would be: +```{pip-cli} +$ pip install "pkg @ vcs+protocol://repo_url/#subdirectory=pkg_dir" +``` + +or: + ```{pip-cli} $ pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" ```