Skip to content

Commit

Permalink
Add dedicated page for VCS support
Browse files Browse the repository at this point in the history
  • Loading branch information
@pradyunsg
pradyunsg committed Jan 19, 2021
1 parent a2b45d1 commit 5805e74
Show file tree
Hide file tree
Showing 3 changed files with 163 additions and 152 deletions.
152 changes: 0 additions & 152 deletions docs/html/cli/pip_install.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -367,158 +367,6 @@ that enables installation of pre-releases and development releases.
.. _pre-releases: https://www.python.org/dev/peps/pep-0440/#handling-of-pre-releases


.. _`VCS Support`:

VCS Support
-----------

pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects
the type of VCS using URL prefixes: ``git+``, ``hg+``, ``svn+``, and ``bzr+``.

pip requires a working VCS command on your path: ``git``, ``hg``, ``svn``, or
``bzr``.

VCS projects can be installed in :ref:`editable mode <editable-installs>` (using
the :ref:`--editable <install_--editable>` option) or not.

* For editable installs, the clone location by default is ``<venv
path>/src/SomeProject`` in virtual environments, and
``<cwd>/src/SomeProject``
for global installs. The :ref:`--src <install_--src>` option can be used to
modify this location.
* For non-editable installs, the project is built locally in a temp dir and then
installed normally. Note that if a satisfactory version of the package is
already installed, the VCS source will not overwrite it without an
``--upgrade`` flag. VCS requirements pin the package version (specified
in the ``setup.py`` file) of the target commit, not necessarily the commit
itself.
* The :ref:`pip freeze` subcommand will record the VCS requirement specifier
(referencing a specific commit) if and only if the install is done using the
editable option.

The "project name" component of the URL suffix ``egg=<project name>``
is used by pip in its dependency logic to identify the project prior
to pip downloading and analyzing the metadata. For projects
where ``setup.py`` is not in the root of project, the "subdirectory" component
is used. The value of the "subdirectory" component should be a path starting
from the root of the project to where ``setup.py`` is located.

If your repository layout is::

pkg_dir
├── setup.py # setup.py for package "pkg"
└── some_module.py
other_dir
└── some_file
some_other_file

Then, to install from this repository, the syntax would be:

.. tab:: Unix/macOS

.. code-block:: shell
python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
.. tab:: Windows

.. code-block:: shell
py -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
Git
^^^

pip currently supports cloning over ``git``, ``git+http``, ``git+https``,
``git+ssh``, ``git+git`` and ``git+file``.

.. warning::

Note that the use of ``git``, ``git+git``, and ``git+http`` is discouraged.
The former two use `the Git Protocol`_, which lacks authentication, and HTTP is
insecure due to lack of TLS based encryption.

Here are the supported forms::

[-e] git+http://git.example.com/MyProject#egg=MyProject
[-e] git+https://git.example.com/MyProject#egg=MyProject
[-e] git+ssh://git.example.com/MyProject#egg=MyProject
[-e] git+file:///home/user/projects/MyProject#egg=MyProject

Passing a branch name, a commit hash, a tag name or a git ref is possible like so::

[-e] git+https://git.example.com/MyProject.git@master#egg=MyProject
[-e] git+https://git.example.com/[email protected]#egg=MyProject
[-e] git+https://git.example.com/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject
[-e] git+https://git.example.com/MyProject.git@refs/pull/123/head#egg=MyProject

When passing a commit hash, specifying a full hash is preferable to a partial
hash because a full hash allows pip to operate more efficiently (e.g. by
making fewer network calls).

.. _`the Git Protocol`: https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols

Mercurial
^^^^^^^^^

The supported schemes are: ``hg+file``, ``hg+http``, ``hg+https``,
``hg+static-http``, and ``hg+ssh``.

Here are the supported forms::

[-e] hg+http://hg.myproject.org/MyProject#egg=MyProject
[-e] hg+https://hg.myproject.org/MyProject#egg=MyProject
[-e] hg+ssh://hg.myproject.org/MyProject#egg=MyProject
[-e] hg+file:///home/user/projects/MyProject#egg=MyProject

You can also specify a revision number, a revision hash, a tag name or a local
branch name like so::

[-e] hg+http://hg.example.com/MyProject@da39a3ee5e6b#egg=MyProject
[-e] hg+http://hg.example.com/MyProject@2019#egg=MyProject
[-e] hg+http://hg.example.com/[email protected]#egg=MyProject
[-e] hg+http://hg.example.com/MyProject@special_feature#egg=MyProject

Subversion
^^^^^^^^^^

pip supports the URL schemes ``svn``, ``svn+svn``, ``svn+http``, ``svn+https``, ``svn+ssh``.

Here are some of the supported forms::

[-e] svn+https://svn.example.com/MyProject#egg=MyProject
[-e] svn+ssh://svn.example.com/MyProject#egg=MyProject
[-e] svn+ssh://[email protected]/MyProject#egg=MyProject

You can also give specific revisions to an SVN URL, like so::

[-e] svn+svn://svn.example.com/svn/MyProject#egg=MyProject
[-e] svn+http://svn.example.com/svn/MyProject/trunk@2019#egg=MyProject

which will check out revision 2019. ``@{20080101}`` would also check
out the revision from 2008-01-01. You can only check out specific
revisions using ``-e svn+...``.

Bazaar
^^^^^^

pip supports Bazaar using the ``bzr+http``, ``bzr+https``, ``bzr+ssh``,
``bzr+sftp``, ``bzr+ftp`` and ``bzr+lp`` schemes.

Here are the supported forms::

[-e] bzr+http://bzr.example.com/MyProject/trunk#egg=MyProject
[-e] bzr+sftp://[email protected]/MyProject/trunk#egg=MyProject
[-e] bzr+ssh://[email protected]/MyProject/trunk#egg=MyProject
[-e] bzr+ftp://[email protected]/MyProject/trunk#egg=MyProject
[-e] bzr+lp:MyProject#egg=MyProject

Tags or revisions can be installed like so::

[-e] bzr+https://bzr.example.com/MyProject/trunk@2019#egg=MyProject
[-e] bzr+http://bzr.example.com/MyProject/[email protected]#egg=MyProject

Using Environment Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down
1 change: 1 addition & 0 deletions docs/html/explanations/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,5 @@ editable-installs
repeatable-installs
requirements-files
user-installs
vcs-support
```
162 changes: 162 additions & 0 deletions docs/html/explanations/vcs-support.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
# VCS Support

pip supports installing from various version control systems (VCS).
This support requires a working executable to be available (for the version
control system being used). It is used through URL prefixes:

- Git -- `git+`
- Mercurial -- `hg+`
- Subversion -- `svn+`
- Bazaar -- `bzr+`

## Supported VCS

### Git

The supported schemes are `git+file`, `git+https`, `git+ssh`, `git+http`,
`git+git` and `git`. Here are some of the supported forms:

```none
git+ssh://git.example.com/MyProject#egg=MyProject
git+file:///home/user/projects/MyProject#egg=MyProject
git+https://git.example.com/MyProject#egg=MyProject
git+http://git.example.com/MyProject#egg=MyProject
```

```{warning}
The use of `git`, `git+git`, and `git+http` schemes is discouraged.
The former two use [the Git Protocol], which lacks authentication, and HTTP is
insecure due to lack of TLS based encryption.
```

[the Git Protocol]: https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols

It is also possible to specify a "git ref" such as branch name, a commit hash or
a tag name:

```none
git+https://git.example.com/MyProject.git@master#egg=MyProject
git+https://git.example.com/[email protected]#egg=MyProject
git+https://git.example.com/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject
git+https://git.example.com/MyProject.git@refs/pull/123/head#egg=MyProject
```

When passing a commit hash, specifying a full hash is preferable to a partial
hash because a full hash allows pip to operate more efficiently (e.g. by
making fewer network calls).

### Mercurial

The supported schemes are `hg+file`, `hg+http`, `hg+https`, `hg+ssh`
and `hg+static-http`. Here are some of the supported forms:

```
hg+http://hg.myproject.org/MyProject#egg=MyProject
hg+https://hg.myproject.org/MyProject#egg=MyProject
hg+ssh://hg.myproject.org/MyProject#egg=MyProject
hg+file:///home/user/projects/MyProject#egg=MyProject
```

It is also possible to specify a revision number, a revision hash, a tag name
or a local branch name:

```none
hg+http://hg.example.com/MyProject@da39a3ee5e6b#egg=MyProject
hg+http://hg.example.com/MyProject@2019#egg=MyProject
hg+http://hg.example.com/[email protected]#egg=MyProject
hg+http://hg.example.com/MyProject@special_feature#egg=MyProject
```

### Subversion

The supported schemes are `svn`, `svn+svn`, `svn+http`, `svn+https` and
`svn+ssh`. Here are some of the supported forms:

```none
svn+https://svn.example.com/MyProject#egg=MyProject
svn+ssh://svn.example.com/MyProject#egg=MyProject
svn+ssh://[email protected]/MyProject#egg=MyProject
```

You can also give specific revisions to an SVN URL, like so:

```none
-e svn+http://svn.example.com/svn/MyProject/trunk@2019#egg=MyProject
-e svn+http://svn.example.com/svn/MyProject/trunk@{20080101}#egg=MyProject
```

Note that you need to use {ref}`Editable VCS installs` for using specific
revisions.

### Bazaar

The supported schemes are `bzr+http`, `bzr+https`, `bzr+ssh`, `bzr+sftp`,
`bzr+ftp` and `bzr+lp`. Here are the supported forms:

```none
bzr+http://bzr.example.com/MyProject/trunk#egg=MyProject
bzr+sftp://[email protected]/MyProject/trunk#egg=MyProject
bzr+ssh://[email protected]/MyProject/trunk#egg=MyProject
bzr+ftp://[email protected]/MyProject/trunk#egg=MyProject
bzr+lp:MyProject#egg=MyProject
```

Tags or revisions can be installed like so:

```none
bzr+https://bzr.example.com/MyProject/trunk@2019#egg=MyProject
bzr+http://bzr.example.com/MyProject/[email protected]#egg=MyProject
```

## Editable VCS installs

VCS projects can be installed in {ref}`editable mode <editable-installs>` (using
the {ref}`--editable <install_--editable>` option) or not.

- The default clone location (for editable installs) is:

- `<venv path>/src/SomeProject` in virtual environments
- `<cwd>/src/SomeProject` for global Python installs

The {ref}`--src <install_--src>` option can be used to modify this location.

- For non-editable installs, the project is built locally in a temp dir and then
installed normally.

Note that if a satisfactory version of the package is already installed, the
VCS source will not overwrite it without an `--upgrade` flag. Further, pip
looks at the package version (specified in the `setup.py` file) of the target
commit to determine what action to take on the VCS requirement (not the commit
itself).

The {ref}`pip freeze` subcommand will record the VCS requirement specifier
(referencing a specific commit) only if the install is done with the editable
option.

## URL fragments

pip looks at 2 fragments for VCS URLs:

- `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`

````{admonition} Example
If your repository layout is:
```
pkg_dir
├── setup.py # setup.py for package "pkg"
└── some_module.py
other_dir
└── some_file
some_other_file
```
Then, to install from this repository, the syntax would be:
```{pip-cli}
$ pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
```
````

0 comments on commit 5805e74

Please sign in to comment.