[PATCH v3] doc/bitbake-user-manual-fetching: update the Git fetcher tag description

[PATCH v3] doc/bitbake-user-manual-fetching: update the Git fetcher tag description

[Antonin Godard]

After commit d591d7633fe8 ("fetch/git: Rework tag parameter handling"),
update the description of the tag= parameter for the Git fetcher.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v3:
- Rework tag description as suggested by Richard in v2 (thanks!)
- Rebase on master
- Link to v2: https://lore.kernel.org/r/20250718-new-tag-git-fetcher-v2-0-11240d481a05@bootlin.com

Changes in v2:
- Suggestions by Quentin (thanks!):
  - not mandatory to -> optional
  - correct the rev parameter description
- Link to v1: https://lore.kernel.org/r/20250717-new-tag-git-fetcher-v1-1-77e46929103b@bootlin.com
---
 doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
index 4762d2637a..f357765b77 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
@@ -439,10 +439,12 @@ This fetcher supports the following parameters:
 -  *"rev":* The revision to use for the checkout. If :term:`SRCREV` is also set,
    this parameter must match its value.
 
--  *"tag":* Specifies a tag to use for the checkout. To correctly
-   resolve tags, BitBake must access the network. For that reason, tags
-   are often not used. As far as Git is concerned, the "tag" parameter
-   behaves effectively the same as the "rev" parameter.
+-  *"tag":* Specifies a tag to use when fetching. To correctly resolve
+   tags, BitBake must access the network. If a ``rev`` parameter or
+   :term:`SRCREV` is also specified, network access is not necessary to resolve
+   the tag and instead, it is verified that they both resolve to the same commit
+   SHA at unpack time.  The ``tag`` parameter is optional, but strongly
+   recommended if the checked out revision is a tag.
 
 -  *"subpath":* Limits the checkout to a specific subpath of the tree.
    By default, the whole tree is checked out.

---
base-commit: a8145c84e0899285a5e6a809f1515118b002b106
change-id: 20250717-new-tag-git-fetcher-6287232fc0b1

Best regards,
--  
Antonin Godard <antonin.godard@bootlin.com>