[PATCH] ref-manual: Add "devtool extract/sync" explanation

[PATCH] ref-manual: Add "devtool extract/sync" explanation

[vincent]

From: Vincent Kriek <vincent@coelebs.dev>

Documentation describing the devtool extract and devtool sync commands
were not present. This patch adds basic explanations how the commands
work and why you could use them.

Signed-off-by: Vincent Kriek <vincent@coelebs.dev>
---
 .../ref-manual/devtool-reference.rst          | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 9319addc3c..fbfd038e5c 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -618,3 +618,39 @@ a match.
 
 When you use the ``devtool search`` command, you must supply a keyword.
 The command uses the keyword when searching for a match.
+
+.. _devtool-extract-source-of-recipe:
+
+Extract source of recipe
+========================
+
+Use the ``devtool extract`` command to extract the source of a recipe to the
+directory specified. The extract command can extract the source of a recipe
+with patches applied to a directory on the system, not constrained to the
+devtool workspace.
+
+To extract the source of a recipe use the this command::
+
+        $ devtool extract recipe /path/to/extract/location
+
+In contrary to the ``devtool modify`` command this extracted copy will have no
+impact on builds and can not be integrated back in to recipes by using devtool.
+
+.. _devtool-sync-extracted-source-of-recipe:
+
+Sync extracted source of recipe
+===============================
+
+Use the ``devtool sync`` command to synchronize a previously extracted source
+tree of a recipe with the latest status of the recipe.
+
+To synchronize the extracted source tree of a recipe use this command::
+
+    $ devtool sync recipe /path/to/existing/extract/location
+
+.. note::
+
+   The synchronization of ``devtool sync`` could remove work you have in your
+   checked out tree as it will set the new head of the devtool branch to the
+   latest commit specified by the recipe. The previous devtool branch will be
+   copied to the devtool.bak branch
-- 
2.44.0

Re: [docs] [PATCH] ref-manual: Add "devtool extract/sync" explanation

[Michael Opdenacker]

Hi Vincent

Thanks for your patch!

On 4/14/24 at 20:48, vincent@coelebs.dev wrote:
> From: Vincent Kriek <vincent@coelebs.dev>
>
> Documentation describing the devtool extract and devtool sync commands
> were not present. This patch adds basic explanations how the commands
> work and why you could use them.
>
> Signed-off-by: Vincent Kriek <vincent@coelebs.dev>
> ---
>   .../ref-manual/devtool-reference.rst          | 36 +++++++++++++++++++
>   1 file changed, 36 insertions(+)
>
> diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
> index 9319addc3c..fbfd038e5c 100644
> --- a/documentation/ref-manual/devtool-reference.rst
> +++ b/documentation/ref-manual/devtool-reference.rst
> @@ -618,3 +618,39 @@ a match.
>   
>   When you use the ``devtool search`` command, you must supply a keyword.
>   The command uses the keyword when searching for a match.
> +
> +.. _devtool-extract-source-of-recipe:
> +
> +Extract source of recipe
> +========================
> +
> +Use the ``devtool extract`` command to extract the source of a recipe to the
> +directory specified. The extract command can extract the source of a recipe
> +with patches applied to a directory on the system, not constrained to the
> +devtool workspace.
> +
> +To extract the source of a recipe use the this command::
> +
> +        $ devtool extract recipe /path/to/extract/location
> +
> +In contrary to the ``devtool modify`` command this extracted copy will have no
> +impact on builds and can not be integrated back in to recipes by using devtool.
> +
> +.. _devtool-sync-extracted-source-of-recipe:
> +
> +Sync extracted source of recipe
> +===============================
> +
> +Use the ``devtool sync`` command to synchronize a previously extracted source
> +tree of a recipe with the latest status of the recipe.
> +
> +To synchronize the extracted source tree of a recipe use this command::
> +
> +    $ devtool sync recipe /path/to/existing/extract/location
> +
> +.. note::
> +
> +   The synchronization of ``devtool sync`` could remove work you have in your
> +   checked out tree as it will set the new head of the devtool branch to the
> +   latest commit specified by the recipe. The previous devtool branch will be
> +   copied to the devtool.bak branch


Your patch does apply, but actually, the current documentation already 
mentions "devtool extract" and "devtool sync". See 
https://git.yoctoproject.org/yocto-docs/tree/documentation/ref-manual/devtool-reference.rst#n224

You may have started from an older version of the documentation, or just 
overlooked  such sections.

Unless I'm mistaken, you may merge your changes with the existing 
descriptions, keeping the best of both. Could you send a new version?

Thanks in advance
Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com