Skip to content

Commit 5805e74

Browse files
pradyunsgpradyunsg
committed
Add dedicated page for VCS support
1 parent a2b45d1 commit 5805e74

File tree

3 files changed

+163
-152
lines changed

3 files changed

+163
-152
lines changed

‎docs/html/cli/pip_install.rst

Lines changed: 0 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -367,158 +367,6 @@ that enables installation of pre-releases and development releases.
367367
.. _pre-releases: https://www.python.org/dev/peps/pep-0440/#handling-of-pre-releases
368368

369369

370-
.. _`VCS Support`:
371-
372-
VCS Support
373-
-----------
374-
375-
pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects
376-
the type of VCS using URL prefixes: ``git+``, ``hg+``, ``svn+``, and ``bzr+``.
377-
378-
pip requires a working VCS command on your path: ``git``, ``hg``, ``svn``, or
379-
``bzr``.
380-
381-
VCS projects can be installed in :ref:`editable mode <editable-installs>` (using
382-
the :ref:`--editable <install_--editable>` option) or not.
383-
384-
* For editable installs, the clone location by default is ``<venv
385-
path>/src/SomeProject`` in virtual environments, and
386-
``<cwd>/src/SomeProject``
387-
for global installs. The :ref:`--src <install_--src>` option can be used to
388-
modify this location.
389-
* For non-editable installs, the project is built locally in a temp dir and then
390-
installed normally. Note that if a satisfactory version of the package is
391-
already installed, the VCS source will not overwrite it without an
392-
``--upgrade`` flag. VCS requirements pin the package version (specified
393-
in the ``setup.py`` file) of the target commit, not necessarily the commit
394-
itself.
395-
* The :ref:`pip freeze` subcommand will record the VCS requirement specifier
396-
(referencing a specific commit) if and only if the install is done using the
397-
editable option.
398-
399-
The "project name" component of the URL suffix ``egg=<project name>``
400-
is used by pip in its dependency logic to identify the project prior
401-
to pip downloading and analyzing the metadata. For projects
402-
where ``setup.py`` is not in the root of project, the "subdirectory" component
403-
is used. The value of the "subdirectory" component should be a path starting
404-
from the root of the project to where ``setup.py`` is located.
405-
406-
If your repository layout is::
407-
408-
pkg_dir
409-
├── setup.py # setup.py for package "pkg"
410-
└── some_module.py
411-
other_dir
412-
└── some_file
413-
some_other_file
414-
415-
Then, to install from this repository, the syntax would be:
416-
417-
.. tab:: Unix/macOS
418-
419-
.. code-block:: shell
420-
421-
python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
422-
423-
.. tab:: Windows
424-
425-
.. code-block:: shell
426-
427-
py -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
428-
429-
430-
Git
431-
^^^
432-
433-
pip currently supports cloning over ``git``, ``git+http``, ``git+https``,
434-
``git+ssh``, ``git+git`` and ``git+file``.
435-
436-
.. warning::
437-
438-
Note that the use of ``git``, ``git+git``, and ``git+http`` is discouraged.
439-
The former two use `the Git Protocol`_, which lacks authentication, and HTTP is
440-
insecure due to lack of TLS based encryption.
441-
442-
Here are the supported forms::
443-
444-
[-e] git+http://git.example.com/MyProject#egg=MyProject
445-
[-e] git+https://git.example.com/MyProject#egg=MyProject
446-
[-e] git+ssh://git.example.com/MyProject#egg=MyProject
447-
[-e] git+file:///home/user/projects/MyProject#egg=MyProject
448-
449-
Passing a branch name, a commit hash, a tag name or a git ref is possible like so::
450-
451-
[-e] git+https://git.example.com/MyProject.git@master#egg=MyProject
452-
[-e] git+https://git.example.com/MyProject.git@v1.0#egg=MyProject
453-
[-e] git+https://git.example.com/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject
454-
[-e] git+https://git.example.com/MyProject.git@refs/pull/123/head#egg=MyProject
455-
456-
When passing a commit hash, specifying a full hash is preferable to a partial
457-
hash because a full hash allows pip to operate more efficiently (e.g. by
458-
making fewer network calls).
459-
460-
.. _`the Git Protocol`: https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols
461-
462-
Mercurial
463-
^^^^^^^^^
464-
465-
The supported schemes are: ``hg+file``, ``hg+http``, ``hg+https``,
466-
``hg+static-http``, and ``hg+ssh``.
467-
468-
Here are the supported forms::
469-
470-
[-e] hg+http://hg.myproject.org/MyProject#egg=MyProject
471-
[-e] hg+https://hg.myproject.org/MyProject#egg=MyProject
472-
[-e] hg+ssh://hg.myproject.org/MyProject#egg=MyProject
473-
[-e] hg+file:///home/user/projects/MyProject#egg=MyProject
474-
475-
You can also specify a revision number, a revision hash, a tag name or a local
476-
branch name like so::
477-
478-
[-e] hg+http://hg.example.com/MyProject@da39a3ee5e6b#egg=MyProject
479-
[-e] hg+http://hg.example.com/MyProject@2019#egg=MyProject
480-
[-e] hg+http://hg.example.com/MyProject@v1.0#egg=MyProject
481-
[-e] hg+http://hg.example.com/MyProject@special_feature#egg=MyProject
482-
483-
Subversion
484-
^^^^^^^^^^
485-
486-
pip supports the URL schemes ``svn``, ``svn+svn``, ``svn+http``, ``svn+https``, ``svn+ssh``.
487-
488-
Here are some of the supported forms::
489-
490-
[-e] svn+https://svn.example.com/MyProject#egg=MyProject
491-
[-e] svn+ssh://svn.example.com/MyProject#egg=MyProject
492-
[-e] svn+ssh://user@svn.example.com/MyProject#egg=MyProject
493-
494-
You can also give specific revisions to an SVN URL, like so::
495-
496-
[-e] svn+svn://svn.example.com/svn/MyProject#egg=MyProject
497-
[-e] svn+http://svn.example.com/svn/MyProject/trunk@2019#egg=MyProject
498-
499-
which will check out revision 2019. ``@{20080101}`` would also check
500-
out the revision from 2008-01-01. You can only check out specific
501-
revisions using ``-e svn+...``.
502-
503-
Bazaar
504-
^^^^^^
505-
506-
pip supports Bazaar using the ``bzr+http``, ``bzr+https``, ``bzr+ssh``,
507-
``bzr+sftp``, ``bzr+ftp`` and ``bzr+lp`` schemes.
508-
509-
Here are the supported forms::
510-
511-
[-e] bzr+http://bzr.example.com/MyProject/trunk#egg=MyProject
512-
[-e] bzr+sftp://user@example.com/MyProject/trunk#egg=MyProject
513-
[-e] bzr+ssh://user@example.com/MyProject/trunk#egg=MyProject
514-
[-e] bzr+ftp://user@example.com/MyProject/trunk#egg=MyProject
515-
[-e] bzr+lp:MyProject#egg=MyProject
516-
517-
Tags or revisions can be installed like so::
518-
519-
[-e] bzr+https://bzr.example.com/MyProject/trunk@2019#egg=MyProject
520-
[-e] bzr+http://bzr.example.com/MyProject/trunk@v1.0#egg=MyProject
521-
522370
Using Environment Variables
523371
^^^^^^^^^^^^^^^^^^^^^^^^^^^
524372

‎docs/html/explanations/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,5 @@ editable-installs
1010
repeatable-installs
1111
requirements-files
1212
user-installs
13+
vcs-support
1314
```

‎docs/html/explanations/vcs-support.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# VCS Support
2+
3+
pip supports installing from various version control systems (VCS).
4+
This support requires a working executable to be available (for the version
5+
control system being used). It is used through URL prefixes:
6+
7+
- Git -- `git+`
8+
- Mercurial -- `hg+`
9+
- Subversion -- `svn+`
10+
- Bazaar -- `bzr+`
11+
12+
## Supported VCS
13+
14+
### Git
15+
16+
The supported schemes are `git+file`, `git+https`, `git+ssh`, `git+http`,
17+
`git+git` and `git`. Here are some of the supported forms:
18+
19+
```none
20+
git+ssh://git.example.com/MyProject#egg=MyProject
21+
git+file:///home/user/projects/MyProject#egg=MyProject
22+
git+https://git.example.com/MyProject#egg=MyProject
23+
git+http://git.example.com/MyProject#egg=MyProject
24+
```
25+
26+
```{warning}
27+
The use of `git`, `git+git`, and `git+http` schemes is discouraged.
28+
The former two use [the Git Protocol], which lacks authentication, and HTTP is
29+
insecure due to lack of TLS based encryption.
30+
```
31+
32+
[the Git Protocol]: https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols
33+
34+
It is also possible to specify a "git ref" such as branch name, a commit hash or
35+
a tag name:
36+
37+
```none
38+
git+https://git.example.com/MyProject.git@master#egg=MyProject
39+
git+https://git.example.com/MyProject.git@v1.0#egg=MyProject
40+
git+https://git.example.com/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject
41+
git+https://git.example.com/MyProject.git@refs/pull/123/head#egg=MyProject
42+
```
43+
44+
When passing a commit hash, specifying a full hash is preferable to a partial
45+
hash because a full hash allows pip to operate more efficiently (e.g. by
46+
making fewer network calls).
47+
48+
### Mercurial
49+
50+
The supported schemes are `hg+file`, `hg+http`, `hg+https`, `hg+ssh`
51+
and `hg+static-http`. Here are some of the supported forms:
52+
53+
```
54+
hg+http://hg.myproject.org/MyProject#egg=MyProject
55+
hg+https://hg.myproject.org/MyProject#egg=MyProject
56+
hg+ssh://hg.myproject.org/MyProject#egg=MyProject
57+
hg+file:///home/user/projects/MyProject#egg=MyProject
58+
```
59+
60+
It is also possible to specify a revision number, a revision hash, a tag name
61+
or a local branch name:
62+
63+
```none
64+
hg+http://hg.example.com/MyProject@da39a3ee5e6b#egg=MyProject
65+
hg+http://hg.example.com/MyProject@2019#egg=MyProject
66+
hg+http://hg.example.com/MyProject@v1.0#egg=MyProject
67+
hg+http://hg.example.com/MyProject@special_feature#egg=MyProject
68+
```
69+
70+
### Subversion
71+
72+
The supported schemes are `svn`, `svn+svn`, `svn+http`, `svn+https` and
73+
`svn+ssh`. Here are some of the supported forms:
74+
75+
```none
76+
svn+https://svn.example.com/MyProject#egg=MyProject
77+
svn+ssh://svn.example.com/MyProject#egg=MyProject
78+
svn+ssh://user@svn.example.com/MyProject#egg=MyProject
79+
```
80+
81+
You can also give specific revisions to an SVN URL, like so:
82+
83+
```none
84+
-e svn+http://svn.example.com/svn/MyProject/trunk@2019#egg=MyProject
85+
-e svn+http://svn.example.com/svn/MyProject/trunk@{20080101}#egg=MyProject
86+
```
87+
88+
Note that you need to use {ref}`Editable VCS installs` for using specific
89+
revisions.
90+
91+
### Bazaar
92+
93+
The supported schemes are `bzr+http`, `bzr+https`, `bzr+ssh`, `bzr+sftp`,
94+
`bzr+ftp` and `bzr+lp`. Here are the supported forms:
95+
96+
```none
97+
bzr+http://bzr.example.com/MyProject/trunk#egg=MyProject
98+
bzr+sftp://user@example.com/MyProject/trunk#egg=MyProject
99+
bzr+ssh://user@example.com/MyProject/trunk#egg=MyProject
100+
bzr+ftp://user@example.com/MyProject/trunk#egg=MyProject
101+
bzr+lp:MyProject#egg=MyProject
102+
```
103+
104+
Tags or revisions can be installed like so:
105+
106+
```none
107+
bzr+https://bzr.example.com/MyProject/trunk@2019#egg=MyProject
108+
bzr+http://bzr.example.com/MyProject/trunk@v1.0#egg=MyProject
109+
```
110+
111+
## Editable VCS installs
112+
113+
VCS projects can be installed in {ref}`editable mode <editable-installs>` (using
114+
the {ref}`--editable <install_--editable>` option) or not.
115+
116+
- The default clone location (for editable installs) is:
117+
118+
- `<venv path>/src/SomeProject` in virtual environments
119+
- `<cwd>/src/SomeProject` for global Python installs
120+
121+
The {ref}`--src <install_--src>` option can be used to modify this location.
122+
123+
- For non-editable installs, the project is built locally in a temp dir and then
124+
installed normally.
125+
126+
Note that if a satisfactory version of the package is already installed, the
127+
VCS source will not overwrite it without an `--upgrade` flag. Further, pip
128+
looks at the package version (specified in the `setup.py` file) of the target
129+
commit to determine what action to take on the VCS requirement (not the commit
130+
itself).
131+
132+
The {ref}`pip freeze` subcommand will record the VCS requirement specifier
133+
(referencing a specific commit) only if the install is done with the editable
134+
option.
135+
136+
## URL fragments
137+
138+
pip looks at 2 fragments for VCS URLs:
139+
140+
- `egg`: For specifying the "project name" for use in pip's dependency
141+
resolution logic. eg: `egg=project_name`
142+
- `subdirectory`: For specifying the path to the Python package, when it is not
143+
in the root of the VCS directory. eg: `pkg_dir`
144+
145+
````{admonition} Example
146+
If your repository layout is:
147+
148+
```
149+
pkg_dir
150+
├── setup.py # setup.py for package "pkg"
151+
└── some_module.py
152+
other_dir
153+
└── some_file
154+
some_other_file
155+
```
156+
157+
Then, to install from this repository, the syntax would be:
158+
159+
```{pip-cli}
160+
$ pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
161+
```
162+
````

0 commit comments

Comments
 (0)