LRU (#3455)

* LRU

* Update tutorial/other_features.rst

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

---------

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

reference/commands/list.rst

@@ -8,6 +8,7 @@ conan list
     $ conan list -h
     usage: conan list [-h] [-v [V]] [-f FORMAT] [-p PACKAGE_QUERY] [-r REMOTE]
                   [-c] [-g GRAPH] [-gb GRAPH_BINARIES] [-gr GRAPH_RECIPES]
+                  [--lru LRU]
                   [pattern]
 
     List existing recipes, revisions, or packages in the cache (by default) or the remotes.
@@ -39,6 +40,9 @@ conan list
                             Which binaries are listed
       -gr GRAPH_RECIPES, --graph-recipes GRAPH_RECIPES
                             Which recipes are listed
+      --lru LRU             List recipes and binaries that have not been recently
+                            used. Use a time limit like --lru=5d (days) or
+                            --lru=4w (weeks), h (hours), m(minutes)
 
 The ``conan list`` command can list recipes and packages from the local cache, from the
 specified remotes or from both. This command uses a *reference pattern* as input. The

reference/commands/remove.rst

@@ -1,11 +1,13 @@
+.. _reference_commands_remove:
+
 conan remove
 ============
 
 .. code-block:: text
 
     $ conan remove -h
     usage: conan remove [-h] [-v [V]] [-f FORMAT] [-c] [-p PACKAGE_QUERY]
-                        [-r REMOTE] [-l LIST] [--dry-run]
+                        [-r REMOTE] [-l LIST] [--lru LRU] [--dry-run]
                         [pattern]
 
     Remove recipes or packages from local cache or a remote.
@@ -37,6 +39,9 @@ conan remove
       -r REMOTE, --remote REMOTE
                             Will remove from the specified remote
       -l LIST, --list LIST  Package list file
+      --lru LRU             Remove recipes and binaries that have not been
+                            recently used. Use a time limit like --lru=5d (days)
+                            or --lru=4w (weeks), h (hours), m(minutes)
       --dry-run             Do not remove any items, only print those which would
                             be removed
 

tutorial/other_features.rst

@@ -24,3 +24,44 @@ A typical use case is to "upload to the server the packages that have been built
     $ conan upload --list=pkglist.json -r=myremote -c
 
 See the :ref:`examples in this section<examples_commands_pkglists>`.
+
+
+Removing unused packages from the cache
+---------------------------------------
+
+.. warning::
+
+  The least recently used feature is in **preview**.
+  See :ref:`the Conan stability<stability>` section for more information.
+
+
+The Conan cache does not implement any automatic expiration policy, so its size will be always increasing unless 
+packages are removed or the cache is removed from time to time. It is possible to remove recipes and packages
+that haven't been used recently, while keeping those that have been used in a given time period (Least Recently Used LRU policy). 
+This can be done with the ``--lru`` argument to ``conan remove`` and ``conan list`` commands:
+
+.. code:: bash
+
+    # remove all binaries (but not recipes) not used in the last 4 weeks
+    $ conan remove "*:*" --lru=4w -c
+    # remove all recipes that have not been used in the last 4 weeks (with their binaries)
+    $ conan remove "*" --lru=4w -c
+    
+
+Note that the LRU time follows the rules of the ``remove`` command. If we are removing recipes with a ``"*"`` pattern, only
+the LRU times for recipes will be checked. If a recipe has been recently used, it will keep all the binaries, and if the recipe
+has not been recently used, it will remove itself and all its binaries. If we use a ``"*:*"`` pattern, it will check for binaries only,
+and remove those unused, but always leaving the recipe.
+
+Using ``conan list`` first (take into account that ``conan list`` do not default to list all revisions, as opposed to ``remove``,
+so it is necessary to explicit the ``#*`` to select all revisions if that is the intention) it is possible to create a list of
+least recently used packages:
+
+.. code:: bash
+
+    # List all unused (last 4 weeks) recipe revisions
+    $ conan list "*#*" --lru=4w --format=json > old.json
+    # Remove those recipe revisions (and their binaries)
+    $ conan remove --list=old.json -c
+
+See commands help :ref:`reference_commands_remove` and :ref:`reference_commands_list`.