Merge branch 'contrib/github_pr_12637' into 'master'

Dockerfile with variable depth parameter (GitHub PR)

Closes IDFGH-11513

See merge request espressif/esp-idf!27304

docs/en/api-guides/tools/idf-docker-image.rst

@@ -143,7 +143,8 @@ The Docker file in ESP-IDF repository provides several build arguments which can
 - ``IDF_CLONE_URL``: URL of the repository to clone ESP-IDF from. Can be set to a custom URL when working with a fork of ESP-IDF. The default is ``https://github.com/espressif/esp-idf.git``.
 - ``IDF_CLONE_BRANCH_OR_TAG``: Name of a git branch or tag used when cloning ESP-IDF. This value is passed to the ``git clone`` command using the ``--branch`` argument. The default is ``master``.
 - ``IDF_CHECKOUT_REF``: If this argument is set to a non-empty value, ``git checkout $IDF_CHECKOUT_REF`` command performs after cloning. This argument can be set to the SHA of the specific commit to check out, for example, if some specific commit on a release branch is desired.
-- ``IDF_CLONE_SHALLOW``: If this argument is set to a non-empty value, ``--depth=1 --shallow-submodules`` arguments are be used when performing ``git clone``. This significantly reduces the amount of data downloaded and the size of the resulting Docker image. However, if switching to a different branch in such a "shallow" repository is necessary, an additional ``git fetch origin <branch>`` command must be executed first.
+- ``IDF_CLONE_SHALLOW``: If this argument is set to a non-empty value, ``--depth=1 --shallow-submodules`` arguments are used when performing ``git clone``. Depth can be customized using ``IDF_CLONE_SHALLOW_DEPTH``. Doing a shallow clone significantly reduces the amount of data downloaded and the size of the resulting Docker image. However, if switching to a different branch in such a "shallow" repository is necessary, an additional ``git fetch origin <branch>`` command must be executed first.
+- ``IDF_CLONE_SHALLOW_DEPTH``: This argument specifies the depth value to use when doing a shallow clone. If not set, ``--depth=1`` will be used. This argument has effect only if ``IDF_CLONE_SHALLOW`` is used. Use this argument if you are building a Docker image for a branch, and the image has to contain the latest tag on that branch. To determine the required depth, run ``git describe`` for the given branch and note the offset number. Increment it by 1, then use it as the value of this argument. The resulting image will contain the latest tag on the branch, and consequently ``git describe`` command inside the Docker image will work as expected.
 - ``IDF_INSTALL_TARGETS``: Comma-separated list of ESP-IDF targets to install toolchains for, or ``all`` to install toolchains for all targets. Selecting specific targets reduces the amount of data downloaded and the size of the resulting Docker image. The default is ``all``.
 
 To use these arguments, pass them via the ``--build-arg`` command line option. For example, the following command builds a Docker image with a shallow clone of ESP-IDF v4.4.1 and tools for ESP32-C3 only:

docs/zh_CN/api-guides/tools/idf-docker-image.rst

@@ -143,7 +143,8 @@ ESP-IDF 库中的 Docker 文件提供了以下构建参数，可用于构建自
 - ``IDF_CLONE_URL``：克隆 ESP-IDF 存储库的 URL。在使用 ESP-IDF 分支时，可以将该参数设置为自定义 URL，默认值为 ``https://github.com/espressif/esp-idf.git``。
 - ``IDF_CLONE_BRANCH_OR_TAG``：克隆 ESP-IDF 时使用的 git 分支或标签的名称。该参数将作为 ``git clone`` 命令的 ``--branch`` 参数传递，默认值为 ``master``。
 - ``IDF_CHECKOUT_REF``：如果将此参数设置为非空值，在克隆之后会执行 ``git checkout $IDF_CHECKOUT_REF`` 命令。可以将此参数设置为特定 commit 的 SHA 值，以便切换到所需的版本分支或 commit。例如，在希望使用特定版本分支上的某个 commit 时，就可以将此参数设置为该 commit 的 SHA 值。
-- ``IDF_CLONE_SHALLOW``：如果将此参数设置为非空值，则会在执行 ``git clone`` 时使用 ``--depth=1 --shallow-submodules`` 参数。这可以极大减少下载的数据量及生成的 Docker 镜像大小。然而，如果需要切换到此类“浅层”存储库中的其他分支，必须先执行额外的 ``git fetch origin <branch>`` 命令。
+- ``IDF_CLONE_SHALLOW``：如果将此参数设置为非空值，则会在执行 ``git clone`` 时使用 ``--depth=1 --shallow-submodules`` 参数。浅克隆的深度可以使用 ``IDF_CLONE_SHALLOW_DEPTH`` 设置。浅克隆可以极大减少下载的数据量及生成的 Docker 镜像大小。然而，如果需要切换到此类“浅层”存储库中的其他分支，必须先执行额外的 ``git fetch origin <branch>`` 命令。
+- ``IDF_CLONE_SHALLOW_DEPTH``：此参数指定进行浅克隆时要使用的深度值。如未设置，将使用 ``--depth=1``。此参数仅在使用 ``IDF_CLONE_SHALLOW`` 时有效。如果要为分支构建 Docker 镜像，并且该镜像必须包含该分支上的最新标签，则需使用此参数。要确定所需的深度，请在特定的分支运行 ``git describe`` 命令，并注意偏移值。将偏移值加 1 后即可将其用作 ``IDF_CLONE_SHALLOW_DEPTH`` 参数的值。此过程将确保生成的镜像包含分支上的最新标签，且 Docker 镜像内部的 ``git describe`` 命令也会按预期工作。
 - ``IDF_INSTALL_TARGETS``：以逗号分隔的 ESP-IDF 目标列表，用于安装工具链，或者使用 ``all`` 安装所有目标的工具链。选择特定目标可以减少下载的数据量和生成的 Docker 镜像的大小。该参数默认值为 ``all``。
 
 要使用以上参数，请通过 ``--build-arg`` 命令行选项传递。例如，以下命令使用 ESP-IDF v4.4.1 的浅克隆以及仅适用于 ESP32-C3 的工具链构建了 Docker 镜像：

tools/docker/Dockerfile

@@ -44,12 +44,14 @@ RUN : \
 #   IDF_CLONE_BRANCH_OR_TAG=release/vX.Y
 #   IDF_CHECKOUT_REF=<some commit on release/vX.Y branch>.
 # Use IDF_CLONE_SHALLOW=1 to peform shallow clone (i.e. --depth=1 --shallow-submodules)
+# Use IDF_CLONE_SHALLOW_DEPTH=X to define the depth if IDF_CLONE_SHALLOW is used (i.e. --depth=X)
 # Use IDF_INSTALL_TARGETS to install tools only for selected chip targets (CSV)
 
 ARG IDF_CLONE_URL=https://github.com/espressif/esp-idf.git
 ARG IDF_CLONE_BRANCH_OR_TAG=master
 ARG IDF_CHECKOUT_REF=
 ARG IDF_CLONE_SHALLOW=
+ARG IDF_CLONE_SHALLOW_DEPTH=1
 ARG IDF_INSTALL_TARGETS=all
 
 ENV IDF_PATH=/opt/esp/idf
@@ -65,14 +67,14 @@ RUN if [ "$IDF_INSTALL_TARGETS" = "all" ]; then \
 
 RUN echo IDF_CHECKOUT_REF=$IDF_CHECKOUT_REF IDF_CLONE_BRANCH_OR_TAG=$IDF_CLONE_BRANCH_OR_TAG && \
     git clone --recursive \
-      ${IDF_CLONE_SHALLOW:+--depth=1 --shallow-submodules} \
+      ${IDF_CLONE_SHALLOW:+--depth=${IDF_CLONE_SHALLOW_DEPTH} --shallow-submodules} \
       ${IDF_CLONE_BRANCH_OR_TAG:+-b $IDF_CLONE_BRANCH_OR_TAG} \
       $IDF_CLONE_URL $IDF_PATH && \
     git config --system --add safe.directory $IDF_PATH && \
     if [ -n "$IDF_CHECKOUT_REF" ]; then \
       cd $IDF_PATH && \
       if [ -n "$IDF_CLONE_SHALLOW" ]; then \
-        git fetch origin --depth=1 --recurse-submodules ${IDF_CHECKOUT_REF}; \
+        git fetch origin --depth=${IDF_CLONE_SHALLOW_DEPTH} --recurse-submodules ${IDF_CHECKOUT_REF}; \
       fi && \
       git checkout $IDF_CHECKOUT_REF && \
       git submodule update --init --recursive; \