@@ -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/``.
[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(+) --- base-commit: 112bddd8fc684fbdd71139429251b127739f863b change-id: 20260326-add-subpath-warning-153cf3877495