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

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

## Let the server name an ephemeral branch

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

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

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](/docs/repos/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">
  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.
</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/repos/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>