github.com/treeverse/lakefs@v1.24.1-0.20240520134607-95648127bfb0/docs/understand/how/merge.md (about)

     1  ---
     2  title: Merge
     3  description: Using lakeFS, you can merge different commits and references into a branch. The purpose of this document is to explain how to use this feature.
     4  parent: How lakeFS Works
     5  grand_parent: Understanding lakeFS
     6  redirect_from:
     7    - /reference/merge.html
     8    - /understand/merge.html
     9  ---
    10  
    11  # Merges in lakeFS
    12  
    13  The merge operation in lakeFS is similar to Git. It incorporates changes from a _merge source_ (a commit/reference) into a _merge destination_ (a **branch**). 
    14  
    15  ## How does it work?
    16  
    17  lakeFS first finds the [merge base](https://git-scm.com/docs/git-merge-base#_description): the nearest common ancestor of the two commits.
    18  It can now perform a _three-way merge_, by examining the presence and identity of files in each commit. In the table
    19  below, "A", "B" and "C" are possible file contents, "X" is a missing file, and "conflict"
    20  (which only appears as a result) is a merge failure.
    21  
    22  | **In base** | **In source** | **In destination** | **Result** | **Comment**                                    |
    23  |:-----------:|:-------------:|:------------------:|:----------:|:-----------------------------------------------|
    24  |      A      |       A       |         A          |     A      | Unchanged file                                 |
    25  |      A      |       B       |         B          |     B      | Files changed on both sides in same way        |
    26  |      A      |       B       |         C          |  conflict  | Files changed on both sides differently        |
    27  |      A      |       A       |         B          |     B      | File changed only on one branch                |
    28  |      A      |       B       |         A          |     B      | File changed only on one branch                |
    29  |      A      |       X       |         X          |     X      | Files deleted on both sides                    |
    30  |      A      |       B       |         X          |  conflict  | File changed on one side, deleted on the other |
    31  |      A      |       X       |         B          |  conflict  | File changed on one side, deleted on the other |
    32  |      A      |       A       |         X          |     X      | File deleted on one side                       |
    33  |      A      |       X       |         A          |     X      | File deleted on one side                       |
    34  
    35  ## Merge Strategies
    36  
    37  The [API]({% link reference/api.md %}) and [`lakectl`][lakectl-merge] allow passing an optional `strategy` flag with the following values:
    38  
    39  ### `source-wins`
    40  
    41  In case of a conflict, merge will pick the source objects.
    42  
    43  #### Example
    44  
    45  ```bash
    46  lakectl merge lakefs://example-repo/validated-data lakefs://example-repo/production --strategy source-wins
    47  ```
    48  When a merge conflict arises, the conflicting objects in the `validated-data` branch will be chosen to end up in `production`.
    49  
    50  ### `dest-wins`
    51  
    52  In case of a conflict, merge will pick the destination objects.
    53  
    54  #### Example
    55  
    56  ```bash
    57  lakectl merge lakefs://example-repo/validated-data lakefs://example-repo/production --strategy dest-wins
    58  ```
    59  When a merge conflict arises, the conflicting objects in the `production` branch will be chosen to end up in `validated-data`. The `production` branch will not be affected by object changes from `validated-data` conflicting objects.
    60  
    61  The strategy will affect all conflicting objects in the merge if it is set. Currently it is not possible to treat conflicts individually.
    62  
    63  As a format-agnostic system, lakeFS currently merges by complete files. Format-specific and
    64  other user-defined merge strategies for handling conflicts are on the roadmap.
    65  
    66  
    67  [lakectl-merge]:  {% link reference/cli.md %}#lakectl-merge