From 92573d404ae1de64a5652576db1596b01fde4e50 Mon Sep 17 00:00:00 2001 From: Moritz Schubotz Date: Tue, 16 Nov 2021 10:19:53 +0100 Subject: Improve documentation on pretended version Explain that the pretended version is only used in the intermediate layer. --- README.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index 00773a6..38dd93a 100644 --- a/README.rst +++ b/README.rst @@ -214,7 +214,8 @@ Usage from Docker By default, docker will not copy the ``.git`` folder into your container. Therefore, builds with version inference might fail. -Consequently, you can use the following snipped to infer the version from the host os without copying the entire ``.git`` folder to your Dockerfile. +Consequently, you can use the following snipped to infer the version from +the host os without copying the entire ``.git`` folder to your Dockerfile. .. code:: dockerfile @@ -222,18 +223,23 @@ Consequently, you can use the following snipped to infer the version from the ho pip install --no-cache-dir -e . However, this build step introduces a dependency to the state of your local -.git folder the build cache. -To optimize build caching, one can use ``SETUPTOOLS_SCM_PRETEND_VERSION=1`` in -previous build step, so that a full docker-file might look like that: +.git folder the build cache and triggers the long-running pip install process on every build. +To optimize build caching, one can use an environment variable to pretend a pseudo +version that is used to cache the results of the pip install process: .. code:: dockerfile FROM python COPY pyproject.toml - RUN SETUPTOOLS_SCM_PRETEND_VERSION=1 pip install -e .[test] + RUN SETUPTOOLS_SCM_PRETEND_VERSION=ignore pip install -e .[test] RUN --mount=source=.git,target=.git,type=bind pip install -e . -Running this Dockerfile requires docker with BuildKit enabled `[docs] `_. +Note that running this Dockerfile requires docker with BuildKit enabled +`[docs] `_. + +To avoid BuildKit and mounting of the .git folder altogether, one can also pass the desired +version as a build argument. Note that ``SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${UPPERCASED_DIST_NAME}`` +is preferred over ``SETUPTOOLS_SCM_PRETEND_VERSION``. Notable Plugins --------------- -- cgit v1.2.1