Implementation:Treeverse LakeFS MergeIntoBranch

Knowledge Sources	lakeFS lakeFS API Reference
Domains	Data_Version_Control, REST_API
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for merging a source reference into a destination branch in a lakeFS repository provided by the lakeFS REST API.

Description

The mergeIntoBranch endpoint performs a three-way merge of a source reference (branch, commit, or tag) into a destination branch. The operation computes the merge base, identifies differences, resolves conflicts according to the specified strategy, and creates a merge commit on the destination branch. Pre-merge hooks, if configured, are executed before the merge is finalized. The endpoint supports optional squash merge mode, which collapses all source commits into a single merge commit.

Usage

Use this API when:

Promoting validated data from a feature or staging branch into the production main branch.
Integrating outputs from parallel data pipelines into a consolidated branch.
Applying hotfixes or corrections from a patch branch into multiple target branches.
Automating merge operations as part of CI/CD workflows for data pipelines.

Code Reference

Source Location

Repository: lakeFS
File: api/swagger.yml (lines 4678-4742)

Signature

/repositories/{repository}/refs/{sourceRef}/merge/{destinationBranch}:
  post:
    operationId: mergeIntoBranch
    summary: merge references
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: sourceRef
        required: true
        schema:
          type: string
      - in: path
        name: destinationBranch
        required: true
        schema:
          type: string
    requestBody:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Merge"
    responses:
      200:
        description: merge completed
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MergeResult"
      409:
        description: Conflict
      412:
        description: Precondition Failed (pre-merge hook rejection)

Import

import lakefs

client = lakefs.Client(
    host="http://localhost:8000",
    username="access_key_id",
    password="secret_access_key"
)
repo = lakefs.Repository("my-repo", client=client)
source = repo.ref("experiment-v2")
result = source.merge_into(destination_branch="main")

I/O Contract

Inputs

Name	Type	Required	Description
repository (path param)	string	Yes	Repository name.
sourceRef (path param)	string	Yes	Source reference to merge from (branch name, commit ID, or tag).
destinationBranch (path param)	string	Yes	Destination branch to merge into.
message	string	No	Custom message for the merge commit.
metadata	map[string]string	No	Optional key-value metadata for the merge commit.
strategy	string	No	Conflict resolution strategy: `"source-wins"` or `"dest-wins"`.
force	boolean	No	Force the merge even in certain edge cases. Defaults to `false`.
allow_empty	boolean	No	Allow merge even if there are no changes to merge. Defaults to `false`.
squash_merge	boolean	No	Squash all source commits into a single merge commit. Defaults to `false`.

Outputs

Name	Type	Description
reference	string	The commit reference of the resulting merge commit on the destination branch.

Usage Examples

Merge a Branch Using the Python SDK

import lakefs

client = lakefs.Client(
    host="http://localhost:8000",
    username="AKIAIOSFODNN7EXAMPLE",
    password="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
)

repo = lakefs.Repository("my-data-repo", client=client)

# Merge experiment branch into main
result = repo.ref("experiment-v2").merge_into(
    destination_branch="main",
    message="Merge experiment v2 results into production"
)
print(f"Merge commit: {result}")

Merge Using curl

curl -X POST http://localhost:8000/api/v1/repositories/my-data-repo/refs/experiment-v2/merge/main \
  -H "Content-Type: application/json" \
  -u "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -d '{
    "message": "Merge experiment v2 results into production"
  }'

Merge With Source-Wins Conflict Resolution

curl -X POST http://localhost:8000/api/v1/repositories/my-data-repo/refs/experiment-v2/merge/main \
  -H "Content-Type: application/json" \
  -u "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -d '{
    "message": "Force merge with source-wins strategy",
    "strategy": "source-wins",
    "metadata": {
      "approved_by": "data-team-lead",
      "ticket": "DATA-1234"
    }
  }'

Squash Merge

import lakefs

client = lakefs.Client(
    host="http://localhost:8000",
    username="AKIAIOSFODNN7EXAMPLE",
    password="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
)

repo = lakefs.Repository("my-data-repo", client=client)

# Squash merge: collapse all experiment commits into one merge commit
result = repo.ref("experiment-v2").merge_into(
    destination_branch="main",
    message="Squash merge experiment v2",
)
print(f"Squash merge commit: {result}")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment