> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# repo.createBranch()

> Create a named or server-named branch from an existing revision.

> [!WARNING]
>
> This page documents the earlier Code Storage SDKs: `@pierre/storage`, `pierre-storage`, and
> `code-storage-go`. New code uses the [Pierre SDK](https://code.storage/docs/sdks.md). To move code to the new SDK, use the
> [`pierre-migrate`
> skill](https://github.com/pierrecomputer/skills/tree/main/skills/pierre-migrate).

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
const branch = await repo.createBranch({
  baseRef: 'main', // source branch
  targetBranch: 'feature/new-onboarding',
  // baseIsEphemeral: true,
  // targetIsEphemeral: true,
});

console.log(branch.targetBranch); // 'feature/new-onboarding'
console.log(branch.commitSha); // tip SHA when available
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
branch = await repo.create_branch(
    base_ref="main",
    target_branch="feature/new-onboarding",
    # base_is_ephemeral=True,
    # target_is_ephemeral=True,
)

print(branch["target_branch"])
print(branch["commit_sha"])
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
// Create a new branch
branch, err := repo.CreateBranch(context.Background(), storage.CreateBranchOptions{
	BaseRef:      "main",
	TargetBranch: "feature/new-onboarding",
})

fmt.Println(branch.TargetBranch)
fmt.Println(branch.CommitSHA)
```

Toggle `baseIsEphemeral`/`targetIsEphemeral` to work with ephemeral refs. The method returns the API
message plus the resolved branch metadata so you can confirm creation before pushing commits.

## Let the server name an ephemeral branch

Omit the target branch to let Code Storage allocate a name.

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
const stateBranch = await repo.createBranch({
  baseRef: '0123456789abcdef0123456789abcdef01234567',
  targetIsEphemeral: true,
});

console.log(stateBranch.targetBranch); // '<opaque-id>'
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
state_branch = await repo.create_branch(
    base_ref="0123456789abcdef0123456789abcdef01234567",
    target_is_ephemeral=True,
)

print(state_branch["target_branch"])
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
stateBranch, err := repo.CreateBranch(context.Background(), storage.CreateBranchOptions{
	BaseRef:           "0123456789abcdef0123456789abcdef01234567",
	TargetIsEphemeral: true,
})

fmt.Println(stateBranch.TargetBranch)
```

Each call allocates a new branch. If a caller retries after an unknown result, it can create another
branch. Store the returned branch name and delete any branch that the caller no longer needs.

See [Ephemeral Namespace](https://code.storage/docs/repos/ephemeral-branches.md) for namespace behavior.

## Options

**baseRef** `string`

Source branch name, full `refs/heads/*` ref, full `refs/tags/*` ref, or full commit SHA. Python:
`base_ref`. Go: `BaseRef`.

**baseBranch** `string`

Deprecated. Use `baseRef` instead. A call must include this option or `baseRef`. When you send
both options, `baseRef` takes precedence. Python: `base_branch`. Go: `BaseBranch`.

Only an exact 40-character hexadecimal SHA uses the revision path. An abbreviated SHA or a revision
expression returns `400`.

**targetBranch** `string`

Optional destination branch name. Omit it to let the server allocate a name. It can match the
source branch name when you move between namespaces.

**baseIsEphemeral** `boolean`

`true` resolves a branch from the ephemeral namespace. It rejects a tag ref and does not change a
full SHA. With the default `false`, the API rejects all `refs/namespaces/*` refs, including
ephemeral refs.

**targetIsEphemeral** `boolean`

`true` to create/update an ephemeral branch instead of the default namespace.

**refPolicies** `object[]`

Ordered ref policy rules (`{ pattern, ops? }`) in the JWT for this call. Code Storage uses the first rule that matches the target ref. Python: `ref_policies`. Go: `RefPolicies` with type `storage.RefPolicyList`. See [Ref Policies](https://code.storage/docs/repos/ref-policies.md).

## Response

**message** `string`

Confirmation message

**targetBranch** `string`

The created branch name

**targetIsEphemeral** `boolean`

Whether the branch is in the ephemeral namespace

**commitSha** `string`

The tip commit SHA of the new branch


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.