[PATCH v2 0/2] Update the Git fetcher tag and rev descriptions

[PATCH v2 0/2] Update the Git fetcher tag and rev descriptions

[Antonin Godard]

Signed-off-by: Antonin Godard <antonin.godard@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

---
Antonin Godard (2):
      doc/bitbake-user-manual-fetching: update the Git fetcher tag description
      doc/bitbake-user-manual-fetching: remove 'rev' default value

 doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)
---
base-commit: 09f29a4968841ee5070f70277ba8c253bb14f017
change-id: 20250717-new-tag-git-fetcher-6287232fc0b1

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

[PATCH v2 1/2] 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>
---
 doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 9 +++++----
 1 file changed, 5 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 a2c2432db1..51c9a81e03 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
@@ -439,10 +439,11 @@ This fetcher supports the following parameters:
 -  *"rev":* The revision to use for the checkout. The default is
    "master".
 
--  *"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 match against the supplied revision (``rev=``).
+   This does not replace the ``rev`` parameter: the ``tag`` parameter should
+   only be specified if you want to verify that the tag commit SHA matches the
+   supplied ``rev`` SHA. 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.

-- 
2.50.0

[PATCH v2 2/2] doc/bitbake-user-manual-fetching: remove 'rev' default value

[Antonin Godard]

Remove rev's "master" default value. Mention that it must match SRCREV,
if set.

Reported-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
index 51c9a81e03..d4496a9fb7 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
@@ -436,8 +436,8 @@ This fetcher supports the following parameters:
    "nobranch" is set to "1", this is a mandatory parameter. The number of
    branch parameters must match the number of name parameters.
 
--  *"rev":* The revision to use for the checkout. The default is
-   "master".
+-  *"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 match against the supplied revision (``rev=``).
    This does not replace the ``rev`` parameter: the ``tag`` parameter should

-- 
2.50.0

Re: [docs] [PATCH v2 1/2] doc/bitbake-user-manual-fetching: update the Git fetcher tag description

[Richard Purdie]

On Fri, 2025-07-18 at 11:06 +0200, Antonin Godard via lists.yoctoproject.org wrote:
> 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>
> ---
>  doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 9 +++++----
>  1 file changed, 5 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 a2c2432db1..51c9a81e03 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> @@ -439,10 +439,11 @@ This fetcher supports the following parameters:
>  -  *"rev":* The revision to use for the checkout. The default is
>     "master".
>  
> --  *"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 match against the supplied revision (``rev=``).
> +   This does not replace the ``rev`` parameter: the ``tag`` parameter should
> +   only be specified if you want to verify that the tag commit SHA matches the
> +   supplied ``rev`` SHA. The ``tag`` parameter is optional, but strongly
> +   recommended if the checked out revision is a tag.

This isn't quite right since the behaviour of "tag" alone didn't
change, we just altered the behaviour allowing it to be specified with
rev, which makes it much more useful.

It should probably say:

'''
*"tag":* Specifies a tag to use when fetching. To correctly resolve
tags, BitBake must access the network. If a ``rev`` parameter or 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.
'''

Cheers,

Richard

Re: [PATCH v2 2/2] doc/bitbake-user-manual-fetching: remove 'rev' default value

[Quentin Schulz]

Hi Antonin,

On 7/18/25 11:06 AM, Antonin Godard wrote:
> Remove rev's "master" default value. Mention that it must match SRCREV,
> if set.
> 
> Reported-by: Quentin Schulz <quentin.schulz@cherry.de>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> index 51c9a81e03..d4496a9fb7 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> @@ -436,8 +436,8 @@ This fetcher supports the following parameters:
>      "nobranch" is set to "1", this is a mandatory parameter. The number of
>      branch parameters must match the number of name parameters.
>   
> --  *"rev":* The revision to use for the checkout. The default is
> -   "master".
> +-  *"rev":* The revision to use for the checkout. If :term:`SRCREV` is also set,
> +   this parameter must match its value.
>   

This seems correct to me.

There's a second occurrence of that rev parameter in the docs for svn, 
so we should probably document that as well. Funnily enough, the svn 
fetcher has the same logic as the git fetcher except that it overrides 
the revision with the one from the rev= parameter, but the SRCREV != rev 
param is still performed as well as checking for a tag.

Anyway, would be nice to update the description for the svn fetcher too!

Cheers,
Quentin