diff --git a/README.md b/README.md index 9c2f00b3..5a5d4ca5 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ Pipenv: Python Development Workflow for Humans ============================================== -[![image](https://img.shields.io/pypi/v/pipenv.svg)](https://pypi.python.org/pypi/pipenv) -[![image](https://img.shields.io/pypi/l/pipenv.svg)](https://pypi.python.org/pypi/pipenv) +[![image](https://img.shields.io/pypi/v/pipenv.svg)](https://python.org/pypi/pipenv) +[![image](https://img.shields.io/pypi/l/pipenv.svg)](https://python.org/pypi/pipenv) [![image](https://badge.buildkite.com/79c7eccf056b17c3151f3c4d0e4c4b8b724539d84f1e037b9b.svg?branch=master)](https://code.kennethreitz.org/source/pipenv/) -[![image](https://img.shields.io/pypi/pyversions/pipenv.svg)](https://pypi.python.org/pypi/pipenv) +[![image](https://img.shields.io/pypi/pyversions/pipenv.svg)](https://python.org/pypi/pipenv) [![image](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/kennethreitz) ------------------------------------------------------------------------ @@ -216,6 +216,29 @@ Install packages: To activate this project's virtualenv, run the following: $ pipenv shell +Installing from git: + +You can install packages with pipenv from git and other version control systems using URLs formatted according to the following rule: + + +:////@# + +The only optional section is the `@` section. When using git over SSH, you may use the shorthand vcs and scheme alias `git+git@:/@#`. Note that this is translated to `git+ssh://git@` when parsed. + +Valid values for `` include `git`, `bzr`, `svn`, and `hg`. Valid values for `` include `http,`, `https`, `ssh`, and `file`. In specific cases you also have access to other schemes: `svn` may be combined with `svn` as a scheme, and `bzr` can be combined with `sftp` and `lp`. + +Note that it is **strongly recommended** that you install any version-controlled dependencies in editable mode, using `pipenv install -e`, in order to ensure that dependency resolution can be performed with an up to date copy of the repository each time it is performed, and that it includes all known dependencies. + +Below is an example usage which installs the git repository located at `https://github.com/requests/requests.git` from tag `v2.19.1` as package name `requests`: + + $ pipenv install -e git+https://github.com/requests/requests.git@v2.19#egg=requests + Creating a Pipfile for this project... + Installing -e git+https://github.com/requests/requests.git@v2.19.1#egg=requests... + [...snipped...] + Adding -e git+https://github.com/requests/requests.git@v2.19.1#egg=requests to Pipfile's [packages]... + [...] + +You can read more about [pip's implementation of vcs support here](https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support). + Install a dev dependency: $ pipenv install pytest --dev diff --git a/docs/basics.rst b/docs/basics.rst index a38d3403..e6afea3f 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -334,17 +334,30 @@ If you experience issues with ``$ pipenv shell``, just check the ``PIPENV_SHELL` ☤ A Note about VCS Dependencies ------------------------------- -Pipenv will resolve the sub–dependencies of VCS dependencies, but only if they are installed in editable mode:: +You can install packages with pipenv from git and other version control systems using URLs formatted according to the following rule:: - $ pipenv install -e git+https://github.com/requests/requests.git#egg=requests + +:////@# + +The only optional section is the ``@`` section. When using git over SSH, you may use the shorthand vcs and scheme alias ``git+git@:/@#``. Note that this is translated to ``git+ssh://git@`` when parsed. + +Note that it is **strongly recommended** that you install any version-controlled dependencies in editable mode, using ``pipenv install -e``, in order to ensure that dependency resolution can be performed with an up to date copy of the repository each time it is performed, and that it includes all known dependencies. + +Below is an example usage which installs the git repository located at ``https://github.com/requests/requests.git`` from tag ``v2.19.1`` as package name ``requests``:: + + $ pipenv install -e git+https://github.com/requests/requests.git@v2.19#egg=requests + Creating a Pipfile for this project... + Installing -e git+https://github.com/requests/requests.git@v2.19.1#egg=requests... + [...snipped...] + Adding -e git+https://github.com/requests/requests.git@v2.19.1#egg=requests to Pipfile's [packages]... + [...] $ cat Pipfile [packages] - requests = {git = "https://github.com/requests/requests.git", editable=true} + requests = {git = "https://github.com/requests/requests.git", editable = true, ref = "2.19.1"} -If editable is not true, sub–dependencies will not be resolved. +Valid values for ```` include ``git``, ``bzr``, ``svn``, and ``hg``. Valid values for ```` include ``http``, ``https``, ``ssh``, and ``file``. In specific cases you also have access to other schemes: ``svn`` may be combined with ``svn`` as a scheme, and ``bzr`` can be combined with ``sftp`` and ``lp``. -For more information about other options available when specifying VCS dependencies, please check the `Pipfile spec `__. +You can read more about pip's implementation of VCS support `here `_. For more information about other options available when specifying VCS dependencies, please check the `Pipfile spec `_. ☤ Pipfile.lock Security Features diff --git a/news/2685.doc b/news/2685.doc new file mode 100644 index 00000000..6f2a0aff --- /dev/null +++ b/news/2685.doc @@ -0,0 +1 @@ +Added simple example to README.md for installing from git. diff --git a/news/2696.trivial b/news/2696.trivial new file mode 100644 index 00000000..dc68eca0 --- /dev/null +++ b/news/2696.trivial @@ -0,0 +1 @@ +Added additional information to error messaging during failed resolution. diff --git a/pipenv/utils.py b/pipenv/utils.py index 9d0427b7..21a1ec20 100644 --- a/pipenv/utils.py +++ b/pipenv/utils.py @@ -310,11 +310,13 @@ def actually_resolve_deps( click_echo( "{0}: Your dependencies could not be resolved. You likely have a " "mismatch in your sub-dependencies.\n " - "You can use {1} to bypass this mechanism, then run {2} to inspect " - "the situation.\n " - "Hint: try {3} if it is a pre-release dependency." + "First try clearing your dependency cache with {1}, then try the original command again.\n " + "Alternatively, you can use {2} to bypass this mechanism, then run " + "{3} to inspect the situation.\n " + "Hint: try {4} if it is a pre-release dependency." "".format( crayons.red("Warning", bold=True), + crayons.red("$ pipenv lock --clear"), crayons.red("$ pipenv install --skip-lock"), crayons.red("$ pipenv graph"), crayons.red("$ pipenv lock --pre"),