> ## 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({
    baseBranch: '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_branch="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{
  	BaseBranch:   "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.

## Options

<ParamField path="baseBranch" type="string" required>
  Source branch to copy from. Combine with `baseIsEphemeral` when promoting from the ephemeral
  namespace.
</ParamField>

<ParamField path="targetBranch" type="string" required>
  Destination branch name. May match `baseBranch` when moving between namespaces.
</ParamField>

<ParamField path="baseIsEphemeral" type="string">
  `true` when the source branch lives in the ephemeral namespace (defaults to `false`).
</ParamField>

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

<ParamField path="refPolicies" type="object[]">
  Ordered per-ref policy rules (`{ pattern, ops? }`) embedded in the per-call JWT. First match wins. Python: `ref_policies`. Go: `RefPolicies` with type `storage.RefPolicyList`. See the [Branch Protection guide](/docs/guides/branch-protection).
</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>