[PATCH] doc/bitbake-user-manual-fetching: add warning on the Git subpath parameter

[PATCH] doc/bitbake-user-manual-fetching: add warning on the Git subpath parameter

[Antonin Godard]

[YOCTO #15558]

Add a warning on the subpath option which has an unexpected behavior
with regards to how the HEAD is updated in the checked out repository.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
index 1dcdc0ffee1..5d7d6f7a34d 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
@@ -380,6 +380,21 @@ This fetcher supports the following parameters:
 -  *"subpath":* Limits the checkout to a specific subpath of the tree.
    By default, the whole tree is checked out.
 
+   .. warning::
+
+      When using this option, the value of :term:`SRCREV` may not be reflected
+      in the checked out repository.
+
+      To achieve a partial checkout of the repository with the ``subpath``
+      option, the BitBake Git fetcher makes use of Git "plumbing" commands: `git
+      read-tree <https://git-scm.com/docs/git-read-tree>`__ and `git
+      checkout-index <https://git-scm.com/docs/git-checkout-index>`__. However,
+      these commands only update the **files** within the repository, and do not
+      update the current ``HEAD`` to point to the commit specified by
+      :term:`SRCREV`. Instead, the value of ``HEAD`` will always point to the
+      tip of the branch specified by the ``branch`` parameter, which may or may
+      not correspond to :term:`SRCREV`.
+
 -  *"destsuffix":* The name of the path in which to place the checkout.
    By default, the path is ``git/``.
 

---
base-commit: 112bddd8fc684fbdd71139429251b127739f863b
change-id: 20260326-add-subpath-warning-153cf3877495