diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst index 6bc15349d..e7851b5e9 100644 --- a/docs/html/cli/pip_install.rst +++ b/docs/html/cli/pip_install.rst @@ -66,7 +66,7 @@ for the name and project version (this is in theory slightly less reliable than using the ``egg_info`` command, but avoids downloading and processing unnecessary numbers of files). -Any URL may use the ``#egg=name`` syntax (see :ref:`VCS Support`) to +Any URL may use the ``#egg=name`` syntax (see :doc:`../topics/vcs-support`) to explicitly state the project name. Satisfying Requirements @@ -372,168 +372,7 @@ that enables installation of pre-releases and development releases. 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 ` (using -the :ref:`--editable ` option) or not. - -* For editable installs, the clone location by default is ``/src/SomeProject`` in virtual environments, and - ``/src/SomeProject`` - for global installs. The :ref:`--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=`` -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@main#egg=MyProject - [-e] git+https://git.example.com/MyProject.git@v1.0#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/MyProject@v1.0#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://user@svn.example.com/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://user@example.com/MyProject/trunk#egg=MyProject - [-e] bzr+ssh://user@example.com/MyProject/trunk#egg=MyProject - [-e] bzr+ftp://user@example.com/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/trunk@v1.0#egg=MyProject - -Using Environment Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Since version 10, pip also makes it possible to use environment variables which -makes it possible to reference private repositories without having to store -access tokens in the requirements file. For example, a private git repository -allowing Basic Auth for authentication can be refenced like this:: - - [-e] git+http://${AUTH_USER}:${AUTH_PASSWORD}@git.example.com/MyProject#egg=MyProject - [-e] git+https://${AUTH_USER}:${AUTH_PASSWORD}@git.example.com/MyProject#egg=MyProject - -.. note:: - - Only ``${VARIABLE}`` is supported, other formats like ``$VARIABLE`` or - ``%VARIABLE%`` won't work. +This is now covered in :doc:`../topics/vcs-support`. Finding Packages ---------------- @@ -801,7 +640,7 @@ You can install local projects or VCS projects in "editable" mode: py -m pip install -e git+http://repo/my_project.git#egg=SomeProject -(See the :ref:`VCS Support` section above for more information on VCS-related syntax.) +(See the :doc:`../topics/vcs-support` section above for more information on VCS-related syntax.) For local projects, the "SomeProject.egg-info" directory is created relative to the project path. This is one advantage over just using ``setup.py develop``, @@ -992,7 +831,7 @@ Examples py -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 -#. Install a project from VCS in "editable" mode. See the sections on :ref:`VCS Support ` and :ref:`Editable Installs `. +#. Install a project from VCS in "editable" mode. See the sections on :doc:`../topics/vcs-support` and :ref:`Editable Installs `. .. tab:: Unix/macOS diff --git a/docs/html/getting-started.md b/docs/html/getting-started.md index 42ac2c934..5c22d1abe 100644 --- a/docs/html/getting-started.md +++ b/docs/html/getting-started.md @@ -47,7 +47,7 @@ $ pip install git+https://github.com/pypa/sampleproject.git@main Successfully installed sampleproject ``` -See {ref}`VCS Support` for more information about this syntax. +See {doc}`topics/vcs-support` for more information about this syntax. ### Install a package from a distribution file diff --git a/docs/html/installation.md b/docs/html/installation.md index e389a8fa4..ecb71a4aa 100644 --- a/docs/html/installation.md +++ b/docs/html/installation.md @@ -13,8 +13,8 @@ Usually, pip is automatically installed if you are: If your Python environment does not have pip installed, there are 2 mechanisms to install pip supported directly by pip's maintainers: -- [`ensurepip`](#using-ensurepip) -- [`get-pip.py`](#using-get-pip-py) +- [`ensurepip`](#ensurepip) +- [`get-pip.py`](#get-pip-py) ### `ensurepip` diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index e86fdb48c..78f5f0730 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1528,7 +1528,7 @@ Setups to test with special attention * Continuous integration/continuous deployment setups -* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :ref:`VCS Support` +* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :doc:`topics/vcs-support` * Installing from source code held in local directories