Skip to content

Commit

Permalink
Clarify the role of the egg URL fragment
Browse files Browse the repository at this point in the history
  • Loading branch information
sbidoul committed Dec 28, 2022
1 parent 8dbb8b9 commit e367c00
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 5 deletions.
17 changes: 12 additions & 5 deletions docs/html/topics/vcs-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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"
```
Expand Down
2 changes: 2 additions & 0 deletions news/11676.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Clarify that the egg URL fragment is only necessary for editable VCS installs, and
otherwise not necessary anymore.

0 comments on commit e367c00

Please sign in to comment.