list/remove/download with version ranges (#3244)

conan-io · Jun 1, 2023 · 5f29ac2 · 5f29ac2
1 parent 7b1071c
commit 5f29ac2
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 14 deletions.
diff --git a/reference/commands/download.rst b/reference/commands/download.rst
@@ -45,7 +45,7 @@ Downloads recipe and binaries to the local cache from the specified remote.
 
 
 You can use patterns to download specific references just like in other commands like
-:command:`conan list` or :command:`conan upload`:
+:command:`conan list` (see the patterns documentation there :ref:`reference_commands_list`) or :command:`conan upload`:
 
 ..  code-block:: bash
     

diff --git a/reference/commands/list.rst b/reference/commands/list.rst
@@ -63,7 +63,8 @@ Listing recipe references
 .. code-block:: text
   :caption: *list all references on local cache*
 
-    $ conan list *
+    # Make sure to quote the argument
+    $ conan list "*"
     Local Cache
       hello
         hello/2.26.1@mycompany/testing
@@ -93,18 +94,35 @@ search.
 .. code-block:: text
     :caption: *list all versions of a reference, equivalent to the previous one*
 
-    $ conan list zlib/*
+    # Make sure to quote the argument
+    $ conan list "zlib/*"
     Local Cache
       zlib
         zlib/1.2.11
         zlib/1.2.12
 
+You can also use version ranges in the version field to define the versions you want:
+
+.. code-block:: text
+    :caption: *list version ranges*
+
+    # Make sure to quote the argument
+    $ conan list "zlib/[<1.2.12]" -r=conancenter
+    Local Cache
+      zlib
+        zlib/1.2.11
+    $ conan list "zlib/[>1.2.11]" -r=conancenter
+    Local Cache
+      zlib
+        zlib/1.2.12
+        zlib/1.2.13
+
 Use the pattern for searching only references matching a specific channel:
 
 .. code-block:: text
     :caption: *list references with 'stable' channel*
 
-    $ conan list */*@*/stable
+    $ conan list "*/*@*/stable"
     Local Cache
       hello
         hello/2.3.2@mycompany/stable
@@ -145,7 +163,7 @@ To list all recipe revisions use the ``*`` wildcard:
 .. code-block:: text
   :caption: *list all recipe revisions*
 
-    $ conan list zlib/1.2.11#*
+    $ conan list "zlib/1.2.11#*""
     Local Cache
       zlib
         zlib/1.2.11
@@ -166,7 +184,8 @@ using ``name/version@user/channel:*`` as the pattern:
 .. code-block:: text
   :caption: *list all package IDs for latest recipe revision*
 
-    $ conan list zlib/1.2.11:*
+    # Make sure to quote the argument
+    $ conan list "zlib/1.2.11:*"
     Local Cache
       zlib
         zlib/1.2.11
@@ -208,7 +227,8 @@ revision ``#`` part:
 .. code-block:: text
   :caption: *list all the package IDs for all the recipe revisions*
 
-    $ conan list zlib/1.2.11#*:*
+    # Make sure to quote the argument
+    $ conan list "zlib/1.2.11#*:*"
     zlib
         zlib/1.2.11
           revisions
@@ -266,7 +286,8 @@ To list all the package revisions for for the latest recipe revision:
 .. code-block:: text
   :caption: *list all the package revisions for all package-ids the latest recipe revision*
 
-    $ conan list zlib/1.2.11:*#*
+    # Make sure to quote the argument
+    $ conan list "zlib/1.2.11:*#*"
     Local Cache
       zlib
         zlib/1.2.11
@@ -305,7 +326,8 @@ with the following structure:
 
 .. code-block:: text
 
-  $ conan list zlib/1.2.11:*#* --format=json
+  # Make sure to quote the argument
+  $ conan list "zlib/1.2.11:*#*" --format=json
   {
     "Local Cache": {
       "zli/1.0.0": {

diff --git a/reference/commands/remove.rst b/reference/commands/remove.rst
@@ -40,6 +40,9 @@ 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.
 
+
+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. 
+
 To remove recipes and their associated package binaries from the local cache:
 
 
@@ -48,12 +51,15 @@ To remove recipes and their associated package binaries from the local cache:
     $ conan remove "*"
     # Removes everything from the cache
 
-    $ conan remove zlib/*
+    $ conan remove "zlib/*""
     # Remove all possible versions of zlib, including all recipes, revisions and packages
 
     $ conan remove zlib/1.2.11
     # Remove zlib/1.2.11, all its revisions and package binaries. Leave other zlib versions
 
+    $ conan remove "zlib/[<1.2.13]"
+    # Remove zlib/1.2.11 and zlib/1.2.12, all its revisions and package binaries.
+
     $ conan remove zlib/1.2.11#latest
     # Remove zlib/1.2.11, only its latest recipe revision and binaries of that revision
     # Leave the other zlib/1.2.11 revisions intact
@@ -72,16 +78,16 @@ pattern including the ``:`` separator of the ``package_id``:
 
 .. code-block:: text
 
-    $ conan remove zlib/1.2.11:*
+    $ conan remove "zlib/1.2.11:*"
     # Removes all the zlib/1.2.11 package binaries from all the recipe revisions
 
-    $ conan remove zlib/*:*
+    $ conan remove "zlib/*:*"
     # Removes all the binaries from all the recipe revisions from all zlib versions
 
-    $ conan remove zlib/1.2.11#latest:*
+    $ conan remove "zlib/1.2.11#latest:*"
     # Removes all the zlib/1.2.11 package binaries only from the latest zlib/1.2.11 recipe revision
 
-    $ conan remove zlib/1.2.11#!latest:*
+    $ conan remove "zlib/1.2.11#!latest:*"
     # Removes all the zlib/1.2.11 package binaries from all the recipe revisions but the latest one
 
     $ conan remove zlib/1.2.11:<package_id>