> ## 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.

# createBranch()

> Create a new branch from an existing branch, optionally using the ephemeral namespace.

<CodeGroup>
  ```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)
  ```
</CodeGroup>

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.

## Create an ephemeral branch from a commit

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

See [Ephemeral Namespace](/docs/guides/ephemeral-branches) for namespace behavior.

## Options

<ParamField path="baseRef" type="string">
  Source branch name, full `refs/heads/*` ref, full `refs/tags/*` ref, or full commit SHA. Python:
  `base_ref`. Go: `BaseRef`.
</ParamField>

<ParamField path="baseBranch" type="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`.
</ParamField>

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

<ParamField path="targetBranch" type="string" required>
  Destination branch name. It can match the source branch name when you move between namespaces.
</ParamField>

<ParamField path="baseIsEphemeral" type="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.
</ParamField>

<ParamField path="targetIsEphemeral" type="boolean">
  `true` to create/update an ephemeral branch instead of the default namespace.
</ParamField>

<ParamField path="refPolicies" type="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](/docs/guides/ref-policies).
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message
</ResponseField>

<ResponseField name="targetBranch" type="string">
  The created branch name
</ResponseField>

<ResponseField name="targetIsEphemeral" type="boolean">
  Whether the branch is in the ephemeral namespace
</ResponseField>

<ResponseField name="commitSha" type="string">
  The tip commit SHA of the new branch
</ResponseField>