---
title: "merge references"
method: POST
path: "/repositories/{repository}/refs/{sourceRef}/merge/{destinationBranch}"
tags: ["refs"]
---

# merge references

`POST /repositories/{repository}/refs/{sourceRef}/merge/{destinationBranch}`

## Request

- Base URL: `/api/v1` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v1/repositories/{repository}/refs/{sourceRef}/merge/{destinationBranch}`
- Auth: one of:
  - HTTP bearer
  - HTTP basic
  - API key in cookie `internal_auth_session`

## Request body

- Merge
  - `message` string
  - `metadata` object
  - `strategy` string: In case of a merge conflict, this option will force the merge process to automatically favor changes from the dest branch ('dest-wins') or from the source branch('source-wins'). In case no selection is made, the merge process will fail in case of a conflict
  - `force` boolean: Allow merge into a read-only branch or into a branch with the same content
  - `allow_empty` boolean: Allow merge when the branches have the same content
  - `squash_merge` boolean: If set, set only the destination branch as a parent, which "squashes" the merge to appear as a single commit on the destination branch. The source commit is no longer a part of the merge commit; consider adding it to the 'metadata' or 'message' fields. This behaves like a GitHub or GitLab "squash merge", or in Git terms 'git merge --squash; git commit ...'.

## Response `200`

merge completed

- MergeResult
  - `reference` string, required

## Other responses

- `400`: Validation Error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Resource Not Found
- `409`: Conflict Deprecated: content schema will return Error format and not an empty MergeResult
- `412`: precondition failed (e.g. a pre-merge hook returned a failure)
- `429`: too many requests
- `default`: Internal Server Error

## Changes

- **2025-07-29** `27799ffec9a5`: 2 info
  - added the non-success response with the status `429`
  - removed the non-success response with the status `420`
- **2025-01-09** `671f609b1a45`: 1 info
  - the `squash_merge` request property default value changed from `true` to `false`
- **2025-01-06** `13aa730b9b28`: 1 info
  - added the new optional request property `squash_merge`
- **2024-09-17** `3b10653a8013`: 1 warning, 2 info
  - removed the request property `squash_merge`
  - added the non-success response with the status `420`
  - removed the non-success response with the status `429`

[Operation history](https://skmtc.dev/treeverse/apis/lakefs-api/changes/repositories/:repository/refs/:sourceRef/merge/:destinationBranch/post.md)

---

[API](https://skmtc.dev/treeverse/apis/lakefs-api.md) - [All operations](https://skmtc.dev/treeverse/apis/lakefs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/treeverse/apis/lakefs-api/revisions/10a3acbbb1fd?raw)