conan lock merge

$ conan lock merge -h
WARN: Downgrading cache from Conan 2.4.1 to 2.2.3
WARN: Applying downgrade migration 2.4_1-migrate.py
Migration: Successfully updated cppstd_compat.py
usage: conan lock merge [-h] [-v [V]] [-cc CORE_CONF] [--lockfile LOCKFILE]
                        [--lockfile-out LOCKFILE_OUT]

Merge 2 or more lockfiles.

options:
  -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
  -cc CORE_CONF, --core-conf CORE_CONF
                        Global configuration for Conan
  --lockfile LOCKFILE   Path to lockfile to be merged
  --lockfile-out LOCKFILE_OUT
                        Filename of the created lockfile

The conan lock merge command takes 2 or more lockfiles and aggregate them, producing one final lockfile. For example, if we have 2 lockfiles lock1.lock and lock2.lock, we can merge both in a final conan.lock one:

# we have 2 lockfiles lock1.lock and lock2.lock
$ conan lock add --requires=pkg/1.1 --lockfile-out=lock1.lock
$ cat lock1.lock
{
    "version": "0.5",
    "requires": [
        "pkg/1.1",
    ],
    "build_requires": [],
    "python_requires": []
}

$ conan lock add --requires=other/2.1 --build-requires=tool/3.2 --lockfile-out=lock2.lock
$ cat lock2.lock
{
    "version": "0.5",
    "requires": [
        "other/2.1"
    ],
    "build_requires": [
        "tool/3.2"
    ],
    "python_requires": []
}

# we can merge both
$ conan lock merge --lockfile=lock1.lock --lockfile=lock2.lock
$ cat conan.lock
{
    "version": "0.5",
    "requires": [
        "pkg/1.1",
        "other/2.1"
    ],
    "build_requires": [
        "tool/3.2"
    ],
    "python_requires": []
}

Similar to the conan lock add command, the conan lock merge:

  • Does keep strict sorting of the lists of versions

  • It does not perform any kind of validation if the packages or versions exist or not, or if they belong to a given dependency graph

  • It is a basic processing of the json files, aggregating them.

  • It doesn’t guarantee that the lockfile will be complete, might require --lockfile-partial if not

  • Recipe revisions, if defined, must contain the timestamp to be sorted correctly.

Warning

  • It is forbidden to manually manipulate a Conan lockfile, changing the strict sorting of references, and that could result in any arbitrary undefined behavior.

  • Recall that it is not possible to conan lock add a version range. The version might be not fully complete (like not providing the revision), but it must be an exact version.

See also

To better understand conan lock merge, it is recommended to first understand lockfiles in general, visit the lockfiles tutorial for a practical introduction to lockfiles.

This conan lock merge command can be useful to consolidate in a single lockfile when for some reasons there are several lockfiles that have diverged. A use case would be to create a multi-configuration lockfile that contains all necessary locked versions for all OSs (Linux, Windows, etc), even if there are conditional dependencies in the graph for the different OSs. At some point when testing a new dependency version, for example, pkg/3.4 new version, when previously pkg/3.3 was already in the graph, we might want to have such a new lockfile cleaning the previous pkg/3.3. If we apply the --lockfile-clean argument that will remove the non-used versions in the lockfile, but that will also remove the OS-dependant dependencies. So something like this could be done: lets say that we have this lockfile (simplified, removed revisions for simplicity) as the result of testing a new pkgb/0.2 version for our main product app1/0.1:

app.lock
{
  "version": "0.5",
  "requires": [
      "pkgb/0.2",
      "pkgb/0.1",
      "pkgawin/0.1",
      "pkganix/0.1",
      "app1/0.1"
  ]
}

The pkgawin and pkganix are dependencies that exist exclusively in Windows and Linux respectively. Everything looks good, pkgb/0.2 new version works fine with our app, and we want to clean the unused things from the lockfile:

$ conan lock create --requires=app1/0.1 --lockfile=app.lock --lockfile-out=win.lock -s os=Windows --lockfile-clean
# Note how both pkgb/0.1 and pkganix are gone
$ cat win.lock
{
  "version": "0.5",
  "requires": [
      "pkgb/0.2",
      "pkgawin/0.1",
      "app1/0.1"
  ]
}
$ conan lock create --requires=app1/0.1 --lockfile=app.lock --lockfile-out=nix.lock -s os=Linux --lockfile-clean
# Note how both pkgb/0.1 and pkgawin are gone
$ cat win.lock
{
  "version": "0.5",
  "requires": [
      "pkgb/0.2",
      "pkganix/0.1",
      "app1/0.1"
  ]
}
  # Finally, merge the 2 clean lockfiles, for keeping just 1 for next iteration
$ conan lock merge --lockfile=win.lock --lockfile=nix.lock --lockfile-out=final.lock
$ cat final.lock
{
  "version": "0.5",
  "requires": [
      "pkgb/0.2",
      "pkgawin/0.1",
      "pkganix/0.1",
      "app1/0.1"
  ]
}