Implementation:Treeverse LakeFS CreateBranch

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

Overview

Concrete tool for creating a new branch within a lakeFS repository provided by the lakeFS REST API.

Description

The createBranch endpoint creates a new branch in the specified repository, pointing to the commit identified by the given source reference. The source can be a branch name, commit ID, or tag. The newly created branch provides an isolated workspace where data changes can be staged and committed independently. Branch creation is a lightweight, zero-copy operation that does not duplicate any underlying data.

Usage

Use this API when:

Creating feature branches for data experimentation or pipeline development.
Setting up isolated environments for A/B testing different data configurations.
Establishing staging branches to validate data pipeline outputs before merging to production.
Automating branch creation as part of CI/CD workflows for data pipelines.

Code Reference

Source Location

Repository: lakeFS
File: api/swagger.yml (lines 4132-4163)

Signature

/repositories/{repository}/branches:
  post:
    operationId: createBranch
    summary: create branch
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BranchCreation"
    responses:
      201:
        description: reference
        content:
          text/html:
            schema:
              type: string

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)
branch = repo.branch("feature-branch").create(source="main")

I/O Contract

Inputs

Name	Type	Required	Description
repository (path param)	string	Yes	Repository name in which to create the branch.
name	string	Yes	Name of the new branch to create.
source	string	Yes	Source reference (branch name, commit ID, or tag) from which to create the branch.
force	boolean	No	If true, reset existing branch to the source reference. Defaults to `false`.
hidden	boolean	No	(Experimental) If true, create a hidden branch. Defaults to `false`.

Outputs

Name	Type	Description
reference	string	The branch reference string (returned as text/html content type).

Usage Examples

Create a Feature 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)

# Create a new branch from main
feature_branch = repo.branch("experiment-v2").create(source="main")
print(f"Branch created: {feature_branch.id}")

Create a Branch Using curl

curl -X POST http://localhost:8000/api/v1/repositories/my-data-repo/branches \
  -H "Content-Type: application/json" \
  -u "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -d '{
    "name": "experiment-v2",
    "source": "main"
  }'

Force-Reset an Existing Branch

curl -X POST http://localhost:8000/api/v1/repositories/my-data-repo/branches \
  -H "Content-Type: application/json" \
  -u "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -d '{
    "name": "experiment-v2",
    "source": "main",
    "force": true
  }'

Related Pages

Implements Principle

Principle:Treeverse_LakeFS_Branch_Creation

Requires Environment

Page Connections

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

Principle

Implementation

Heuristic

Environment