Docs for lockfiles features from 1.35 (#2053)

* modify command reference

* update lock reference

* wip

* document clean-modified for lockfiles

* update bundle docs

* document conan lock install

reference/commands/misc/lock.rst

@@ -5,14 +5,16 @@ conan lock
 
 .. code-block:: bash
 
-    $ conan lock [-h] {update,build-order,clean-modified,create} ...
+    $ conan lock [-h]
+                 {update,build-order,clean-modified,install,create,bundle}
+                 ...
 
 Generates and manipulates lock files.
 
 .. code-block:: text
 
     positional arguments:
-      {update,build-order,clean-modified,create}
+      {update,build-order,clean-modified,install,create,bundle}
                             sub-command help
         update              Complete missing information in the first lockfile
                             with information defined in the second lockfile. Both
@@ -22,7 +24,9 @@ Generates and manipulates lock files.
                             first one
         build-order         Returns build-order
         clean-modified      Clean modified flags
+        install             Install a lockfile
         create              Create a lockfile from a conanfile or a reference
+        bundle              Manages lockfile bundles
 
     optional arguments:
       -h, --help            show this help message and exit
@@ -144,4 +148,104 @@ conan lock clean-modified
         lockfile    Path to the lockfile
 
     optional arguments:
-        -h, --help  show this help message and exit
+        -h, --help  show this help message and exit
+
+conan lock install
+------------------
+
+.. code-block:: bash
+
+    $ conan lock install [-h] [--recipes] [-g GENERATOR] lockfile
+
+.. code-block:: text
+
+    positional arguments:
+    lockfile              Path to the lockfile
+
+    optional arguments:
+    -h, --help            show this help message and exit
+    --recipes             Install only recipes, not binaries
+    -g GENERATOR, --generator GENERATOR
+                            Generators to use
+
+conan lock bundle
+=================
+
+.. code-block:: bash
+
+    $ conan lock bundle [-h] {create,build-order,update,clean-modified} ...
+
+.. code-block:: text
+
+    positional arguments:
+    {create,build-order,update,clean-modified}
+                            sub-command help
+        create              Create lockfile bundle
+        build-order         Returns build-order
+        update              Complete missing information in the first lockfile with information defined in the second lockfile.
+                            Both lockfiles must represent the same graph, and have the same topology with the same identifiers,
+                            i.e. the second lockfile must be an evolution based on the first one
+        clean-modified      Clean modified flag
+
+conan lock bundle create
+------------------------
+
+.. code-block:: bash
+
+    $ conan lock bundle create [-h] [--bundle-out BUNDLE_OUT] lockfiles [lockfiles ...]
+
+.. code-block:: text
+
+    positional arguments:
+    lockfiles             Path to lockfiles
+
+    optional arguments:
+    -h, --help            show this help message and exit
+    --bundle-out BUNDLE_OUT
+                            Filename of the created bundle
+
+conan lock bundle build-order
+-----------------------------
+
+.. code-block:: bash
+
+    $ conan lock bundle build-order [-h] [--json JSON] bundle
+
+.. code-block:: text
+
+    positional arguments:
+    bundle       Path to lockfile bundle
+
+    optional arguments:
+    -h, --help   show this help message and exit
+    --json JSON  generate output file in json format
+
+conan lock bundle update
+------------------------
+
+.. code-block:: bash
+
+    $ conan lock bundle update [-h] bundle
+
+.. code-block:: text
+
+    positional arguments:
+    bundle      Path to lockfile bundle
+
+    optional arguments:
+    -h, --help  show this help message and exit
+
+conan lock bundle clean-modified
+--------------------------------
+
+.. code-block:: bash
+
+    $ conan lock bundle clean-modified [-h] bundle
+
+.. code-block:: text
+
+    positional arguments:
+    bundle      Path to lockfile bundle
+
+    optional arguments:
+    -h, --help  show this help message and exit

versioning/lockfiles/bundle.rst

@@ -191,5 +191,7 @@ updated package revision and status. The ``conan lock bundle update`` does this
 - Scan all connected lockfiles for every ``ref`` recipe reference and ``package_id``, and collect those that have been modified.
 - Propagate the modified information to all the other connected lockfiles.
 
-After ``conan lock bundle update``, all packages sharing the same reference and ``package_id`` should have the same status (marked
-"modified" and same package revision)
+After ``conan lock bundle update``, all packages sharing the same reference and ``package_id`` should
+have the same status (marked "modified" and same package revision). The "modified" state for the
+lockfile bundles can be cleaned using the command ``conan lock bundle clean-modified`` that will
+clean that flag from both the *.bundle* file and the individual *.lock* files.

versioning/lockfiles/ci.rst

@@ -259,3 +259,17 @@ product packages without problems. When the Pull Request is merged there might b
   than the source used in this CI job. Then it is necessary to fire again a new job that will build these packages.
 - If the merge is a clean fast-forward, then the packages that were built in this job would be valid, and could be
   copied from the repository ``conan-build`` to the ``conan-develop``.
+
+After the ``app1`` lockfile is created it could be possible to install all the binaries referenced in
+that lockfile using the :command:`conan lock install`:
+
+.. code:: bash
+
+    $ conan lock install app1_release_updated.lock -g deploy
+
+It is also possible to use this command for just installing the recipes but not the binaries adding
+the ``--recipes`` argument:
+
+.. code:: bash
+
+    $ conan lock install app1_release_updated.lock --recipes

versioning/lockfiles/introduction.rst

@@ -213,9 +213,14 @@ And if we inspect the new *locks/pkgb.lock* file:
         ...
     }
 
-It can be appreciated in *locks/pkgb.lock* that now ``pkgb/0.1@user/testing`` is fully locked, as a package (not a local *conanfile.py*),
-and contains a ``package_id``. So if we try to use this new file for creating the package again, it will error,
-as a package that is fully locked cannot be rebuilt:
+Note that some fields of the lockfile are now completed, as the modified flag, that indicates that
+``pkgb`` was built in the conan create command. That information can be useful in the CI environment
+to know which packages were built by different jobs. Those modified flags can be reset using the
+:command:`conan lock clean-modified`.
+Also, it can be appreciated in *locks/pkgb.lock* that now ``pkgb/0.1@user/testing`` is fully locked, as a
+package (not a local *conanfile.py*), and contains a ``package_id``. So if we try to use this new
+file for creating the package again, it will error, as a package that is fully locked cannot be
+rebuilt:
 
 
 .. code-block:: bash