Create-patch#

Description#

Takes three catalogs, and calculates the patch operation to turn A into B. Returns list of operations and list of conflicts if any.

The create-patch command uses a three-way comparison to produce a patch file that will merge one file tree into another given their common ancestor.

For example, when we have a file tree at time-point 1 and have created a catalog file for this file tree called catalog_week1.json. We do a copy of this state to a new “target” location for use by downstream users. Now work continues in the original location, then we create a new catalog at time point 2 called catalog_week2.json.

If we now want to update the copy of the file tree at our “target” location, and want to know if it is safe to overwrite the tree or if there are local modifications we want to be alerted about, we use the following steps:

  1. First, catalog the “target” location, let’s call this current_target.json.

  2. Then, run the create-patch command to produce the patch file.

  3. When the command returns no differences, empty patch, it indicates no local changes have been made and there are no conflicts.

For usage examples, see the Tutorial. For CLI options, run wrapp create-patch --help.

Python API Reference#

async wrapp.create_patch(
a_catalog: Catalog,
b_catalog: Catalog,
baseline: Catalog,
patch: str | None,
tags: bool = False,
overwrite: bool = False,
ignore: bool = False,
force: bool = False,
context: CommandParameters = CommandParameters(debug=False, verbose=False, dry_run=False, log_file=None, hash_cache_file=None),
) → Tuple[List[Tuple[str, PatchOpBase]], List[Tuple[str, PatchOpBase]]]#

Takes three catalogs, and calculates the patch operation to turn A into B. Returns list of operation and list of conflicts if any.

Create a patch file specifying a list of operations that when applied will convert A to B, where the base catalog specifies the last common ancestor catalog. This will check if A is unmodified, else it will fail. If you want to keep changes in A but copy over all non-conflicting changes, specify the –ignore parameter. In case you want record all operations that will roll back A and make A identical to B, specify the –force parameter. Specify –show to get a detailed list of changes planned.

Parameters:

  • a_catalog – The target catalog

  • b_catalog – The source catalog

  • baseline – The last common catalog before A and B diverged. For simple merge just specify B again.

  • patch – Optionally specify a file name to have the patch written out to a file for later use by apply_patch

  • tags – Flag to respect tags stored in catalogs. If set, differences in tags can cause conflicts and update operations.

  • overwrite – Specify to allow to overwrite the patch file if it already exists

  • ignore – Specify whether to ignore conflicting changes in A, e.g. files modified in both sets, or extra files in A. Don’t touch conflicting files, leave them as is.

  • force – Specify whether to rollback changes, guarantee that after apply patch A becomes B.

  • context – Global configuration parameters

Returns:

(patch_operation_list, conflict_list) tuple both being sorted lists of PatchOp instances. Patch operations must be executed in that order, see PatchOpBase.__lt__.

Raises:

  • FailedCommand – When prerequisites not matched

  • StorageOperationError – Raised when network or file operations fail