|
| 1 | +.. _reference_commands_report: |
| 2 | + |
| 3 | +conan report |
| 4 | +============ |
| 5 | + |
| 6 | +The ``conan report`` command contains subcommands that return information about packages and libraries. |
| 7 | + |
| 8 | +.. autocommand:: |
| 9 | + :command: conan report -h |
| 10 | + |
| 11 | +conan report diff |
| 12 | +----------------- |
| 13 | + |
| 14 | +.. autocommand:: |
| 15 | + :command: conan report diff -h |
| 16 | + |
| 17 | +The ``conan report diff`` command gets the differences between two recipes, also comparing their sources. |
| 18 | +This functionality allows you to compare either two versions of the same recipe or two entirely different recipes. |
| 19 | +Each recipe (old and new) can be identified in one of two ways: by providing both the path to its ``conanfile.py`` and |
| 20 | +its reference, or by specifying just the reference. |
| 21 | + |
| 22 | +When only a reference is given, Conan will first search for the recipe in the local cache; if it is not found, it will |
| 23 | +attempt to download it from the configured remotes. If no revision is explicitly provided, Conan will |
| 24 | +default to using the latest available revision. |
| 25 | + |
| 26 | + |
| 27 | +**Examples** |
| 28 | +~~~~~~~~~~~~ |
| 29 | + |
| 30 | +Remote Reference vs Remote Reference |
| 31 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 32 | + |
| 33 | +If we want to compare versions 1.0 and 2.0 of `mylib` that are available on our `my-remote` remote, it would be: |
| 34 | + |
| 35 | +.. code-block:: bash |
| 36 | +
|
| 37 | + $ conan report diff --old-reference="mylib/1.0" --new-reference="mylib/2.0" -r=my-remote |
| 38 | +
|
| 39 | +Remote Reference vs Local Reference |
| 40 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 41 | + |
| 42 | +Let's suppose we're making changes to the recipe or adding a new version, and we want to compare our changes against a |
| 43 | +version that is in the remote. The version that is not on the remote requires the path to the recipe in order to compare |
| 44 | +it. If it's the old version that we're modifying and it's not found in the remotes, we would use ``--old-path``: |
| 45 | + |
| 46 | +.. code-block:: bash |
| 47 | +
|
| 48 | + $ conan report diff --old-reference="mylib/1.0" --old-path="path/to/recipe" --new-reference="mylib/2.0" |
| 49 | +
|
| 50 | +If, on the other hand, it's the new version that we're modifying then we would use ``--new-path``: |
| 51 | + |
| 52 | +.. code-block:: bash |
| 53 | +
|
| 54 | + $ conan report diff --old-reference="mylib/1.0" --new-reference="mylib/2.0" --new-path="path/to/recipe" |
| 55 | +
|
| 56 | +Local Reference vs Local Reference |
| 57 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 58 | + |
| 59 | +Finally, if we're modifying both versions, we’ll need to provide both paths. They may or may not be the same. |
| 60 | + |
| 61 | +.. code-block:: bash |
| 62 | +
|
| 63 | + $ conan report diff --old-reference="mylib/1.0" --old-path="path/to/recipe" --new-reference="mylib/2.0" --new-path="path/to/recipe" |
| 64 | +
|
| 65 | +Specifying revision |
| 66 | +^^^^^^^^^^^^^^^^^^^ |
| 67 | + |
| 68 | +The command allows you to specify the revision of the package you want to compare. By default, it uses the latest |
| 69 | +revision, but by providing a revision, you can target the exact package you want to compare. This makes it possible |
| 70 | +to do things like compare two identical versions with different revisions in order to check for differences between |
| 71 | +them. |
| 72 | + |
| 73 | +.. code-block:: bash |
| 74 | +
|
| 75 | + $ conan report diff --old-reference="mylib/1.0#oldrev" --new-reference="mylib/1.0#newrev" |
| 76 | +
|
| 77 | +Available formatters |
| 78 | +~~~~~~~~~~~~~~~~~~~~ |
| 79 | + |
| 80 | +Text Formatter |
| 81 | +^^^^^^^^^^^^^^ |
| 82 | + |
| 83 | +By default, it displays this format, which is the format provided by a ``git diff`` between the packages. |
| 84 | + |
| 85 | +JSON Formatter |
| 86 | +^^^^^^^^^^^^^^ |
| 87 | + |
| 88 | +You can obtain the result in JSON format, providing a structured output that is perfect for consumption by other |
| 89 | +scripts. |
| 90 | + |
| 91 | +.. code-block:: bash |
| 92 | +
|
| 93 | + $ conan report diff --old-reference="mylib/1.0" --new-reference="mylib/2.0" --format=json |
| 94 | +
|
| 95 | +HTML Formatter |
| 96 | +^^^^^^^^^^^^^^ |
| 97 | + |
| 98 | +The HTML format generates a small self-contained static web page in a single HTML file. This page lets you conveniently |
| 99 | +visualize the changes in the recipe as well as the changes in the source files of your libraries. It contains filters |
| 100 | +to include and exclude keywords and shortcuts to all the changed files. |
| 101 | + |
| 102 | +.. code-block:: bash |
| 103 | +
|
| 104 | + $ conan report diff --old-reference="zlib/1.3" --new-reference="mylib/1.3.1" --format=html > diff.html |
| 105 | +
|
| 106 | +.. image:: ../../images/conan-report-diff_html.png |
| 107 | + :target: ../../_images/conan-report-diff_html.png |
0 commit comments