new conan report diff documentation

reference/commands.rst

@@ -16,7 +16,6 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
    :maxdepth: 1
    :hidden:
 
-   commands/audit
    commands/cache
    commands/config
    commands/graph
@@ -32,7 +31,6 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
    commands/version
    commands/workspace
 
-- :doc:`conan audit <commands/audit>`: Check for vulnerabilities in your Conan packages
 - :doc:`conan cache <commands/cache>`: Return the path of recipes and packages in the cache
 - :doc:`conan config <commands/config>`: Manage Conan configuration (remotes, settings, plugins, etc)
 - :doc:`conan graph <commands/graph>`: Obtain information about the dependency graph without fetching binaries
@@ -78,6 +76,18 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
 - :doc:`conan test <commands/test>`: Test a package
 - :doc:`conan upload <commands/upload>`: Upload packages from the local cache to a specified remote
 
+**Security Commands**
+
+.. toctree::
+   :caption: Security Commands
+   :maxdepth: 1
+   :hidden:
+
+   commands/audit
+   commands/report
+
+- :doc:`conan audit <commands/audit>`: Checks for vulnerabilities in your Conan packages.
+- :doc:`conan report <commands/report>`: Get information about the packages
 
 .. _commands_output:
 

reference/commands/report.rst

@@ -0,0 +1,10 @@
+conan report
+============
+
+
+The ``conan report`` command contains subcommands that return information about packages and libraries.
+
+.. toctree::
+   :maxdepth: 1
+
+   conan report diff: Get the differences between two recipes, also comparing their sources. <report/diff>

reference/commands/report/diff.rst

@@ -0,0 +1,77 @@
+.. _reference_commands_report_diff:
+
+conan report diff
+=================
+
+.. autocommand::
+    :command: conan report diff -h
+
+The ``conan report diff`` command gets the differences between two recipes, also comparing their sources.
+This functionality allows you to compare either two versions of the same recipe or two entirely different recipes.
+Each recipe (old and new) can be identified in one of two ways: by providing both the path to its ``conanfile.py`` and
+its reference, or by specifying just the reference.
+
+When only a reference is given, Conan will first search for the recipe in the local cache; if it is not found, it will
+attempt to download it from the configured remotes. If no revision is explicitly provided, Conan will
+default to using the latest available revision.
+
+
+**Examples**
+
+
+If we want to compare versions 1.0 and 2.0 of "mylibrary" that are available on our `my-remote` remote, it would be:
+
+.. code-block:: bash
+
+    $ conan report diff --old-reference="mylib/1.0" --new-reference="mylib/2.0" -r=my-remote
+
+
+This is how it would look if one of the versions is on the remote and the other is not. The version that is not on the
+remote requires the path to the recipe in order to compare it.
+
+.. code-block:: bash
+
+    $ conan report diff -or="mylib/1.0" --old-path="path/to/recipe" -nr="mylib/2.0"
+    $ conan report diff -or="mylib/1.0" -nr="mylib/2.0" --new-path="path/to/recipe"
+    $ conan report diff -or="mylib/1.0" --old-path="path/to/recipe" -nr="mylib/2.0" --new-path="path/to/recipe"
+
+The command allows you to specify the revision of the package you want to compare. By default, it uses the latest
+revision, but by providing a revision, you can target the exact package you want to compare. This makes it possible
+to do things like compare two identical versions with different revisions in order to check for differences between
+them.
+
+.. code-block:: bash
+
+    $ conan compare -or="mylib/1.0#oldrev" -nr="mylib/1.0#newrev"
+
+Available formatters
+--------------------
+
+Text Formatter
+^^^^^^^^^^^^^^
+
+By default, it displays this format, which is the format provided by a ``git diff`` between the packages.
+
+JSON Formatter
+^^^^^^^^^^^^^^
+
+You can obtain the result in JSON format, providing a structured output that is perfect for consumption by other
+scripts.
+
+.. code-block:: bash
+
+    $ conan report diff -or="mylib/1.0" -nr="mylib/2.0" --format=json
+
+HTML Formatter
+^^^^^^^^^^^^^^
+
+The HTML format generates a small self-contained static web page in a single HTML file. This page lets you conveniently
+visualize the changes in the recipe as well as the changes in the source files of your libraries. It contains filters
+to include and exclude keywords and shortcuts to all the changed files.
+
+.. code-block:: bash
+
+    $ conan report diff -or="zlib/1.3" -nr="mylib/1.3.1" --format=html
+
+.. image:: ../../../images/conan-report-diff_html.png
+    :target: ../../../_images/conan-report-diff_html.png