remove pkg-lists

examples/commands/pkglists.rst

@@ -173,4 +173,37 @@ We can compute a package list from this file, and then upload those artifacts to
     $ conan upload --list=pkglist.json -r=myremote -c
 
 
+Removing packages lists
+-----------------------
+
+It is also possible to first ``conan list`` and create a list of things to remove, and then remove them:
+
+.. code-block:: bash
+
+    # Removes everything from the cache
+    $ conan list *#* --format=json > pkglist.json
+    $ conan remove --list=pkglist.json  -c
+
+Note that in this case, the default patterns are different in ``list`` and ``remove``, because of the destructive nature of ``conan remove``:
+
+- When a recipe is passed to ``remove`` like ``conan remove zlib/1.2.13``, it will remove the recipe of ``zlib/1.2.13`` and all of its binaries, because the binaries cannot live without the recipe.
+- When a ``package_id`` is passed, like ``conan remove zlib/1.2.13:package_id``, then that specific ``package_id`` will be removed, but the recipe will not
+
+Then the pattern to remove everything will be different if we call directly ``conan remove`` or if we call first ``conan list``, for example:
+
+.. code-block:: bash
+
+    # Removes everything from the cache
+    $ conan remove *
+    # OR via list, we need to explicitly include all revisions
+    $ conan list *#* --format=json > pkglist.json
+    $ conan remove --list=pkglist.json  -c
+
+    # Removes only the binaries from the cache (leave recipes)
+    $ conan remove *:*
+    # OR via list, we need to explicitly include all revisions
+    $ conan list *#*:* --format=json > pkglist.json
+    $ conan remove --list=pkglist.json  -c
+
+
 For more information see the :ref:`Reference commands section<reference_commands>`

reference/commands/download.rst

@@ -86,3 +86,6 @@ If you just want to download the packages belonging to a specific setting, use t
 .. code-block:: bash
 
     $ conan download "zlib/1.2.13#*" -r foo --package-query="os=Linux and arch=x86" 
+
+
+If the ``--format=json`` formatter is specified, the result will be a "PackageList", compatible with other Conan commands, for example the ``conan upload`` command, so it is possible to concatenate a ``download + upload``, using the generated json file. See the :ref:`Packages Lists examples<examples_commands_pkglists>`.

reference/commands/remove.rst

@@ -4,9 +4,9 @@ conan remove
 .. code-block:: text
 
     $ conan remove -h
-    usage: conan remove [-h] [-v [V]] [-c] [-p PACKAGE_QUERY]
-                        [-r REMOTE]
-                        reference
+    usage: conan remove [-h] [-v [V]] [-f FORMAT] [-c] [-p PACKAGE_QUERY]
+                        [-r REMOTE] [-l LIST]
+                        [pattern]
 
     Remove recipes or packages from local cache or a remote.
 
@@ -17,29 +17,38 @@ conan remove
     - If a package reference is specified, it will remove only the package.
 
     positional arguments:
-      reference             Recipe reference or package reference, can contain *
-                            aswildcard at any reference field. e.g: lib/*
+      pattern               A pattern in the form
+                            'pkg/version#revision:package_id#revision', e.g:
+                            zlib/1.2.13:* means all binaries for zlib/1.2.13. If
+                            revision is not specified, it is assumed latest one.
 
     optional arguments:
       -h, --help            show this help message and exit
       -v [V]                Level of detail of the output. Valid options from less
                             verbose to more verbose: -vquiet, -verror, -vwarning,
                             -vnotice, -vstatus, -v or -vverbose, -vv or -vdebug,
                             -vvv or -vtrace
+      -f FORMAT, --format FORMAT
+                            Select the output format: json
       -c, --confirm         Remove without requesting a confirmation
       -p PACKAGE_QUERY, --package-query PACKAGE_QUERY
                             Remove all packages (empty) or provide a query:
                             os=Windows AND (arch=x86 OR compiler=gcc)
       -r REMOTE, --remote REMOTE
                             Will remove from the specified remote
-
+      -l LIST, --list LIST  Package list file
 
 The ``conan remove`` command removes recipes and packages from the local cache or from a
 specified remote. Depending on the patterns specified as argument, it is possible to
 remove a complete package, or just remove the binaries, leaving still the recipe
 available. You can also use the keyword ``!latest`` in the revision part of the pattern to
 avoid removing the latest recipe or package revision of a certain Conan package.
 
+It has 2 possible and mutually exclusive inputs:
+
+- The ``conan remove <pattern>`` pattern-based matching of recipes.
+- The ``conan remove --list=<pkglist>`` that will remove the artifacts specified in the ``pkglist`` json file
+
 
 There are other commands like :command:`conan list` (see the patterns documentation there :ref:`reference_commands_list`), :command:`conan upload` and :command:`conan download`, that take the same patterns. 
 

reference/commands/upload.rst

@@ -58,9 +58,10 @@ It has 2 possible and mutually exclusive inputs:
 - The ``conan upload --list=<pkglist>`` that will upload the artifacts specified in the ``pkglist`` json file
 
 
+If the ``--format=json`` formatter is specified, the result will be a "PackageList", compatible with other Conan commands, for example the ``conan remove`` command, so it is possible to concatenate different commands using the generated json file. See the :ref:`Packages Lists examples<examples_commands_pkglists>`.
+
 The ``--dry-run`` argument will prepare the packages for upload, zip files if necessary, check in the server to see what needs to be uploaded and what is already in the server, but it will not execute the actual upload. 
 
-Use the ``--format=json`` formatter to create a "package lists" json file, compatible with other commands, see the :ref:`packages lists examples in this section<examples_commands_pkglists>`.
 
 Read more
 ---------