Work with branches

Create branches to preview changes and collaborate before publishing.

Branches are a feature of version control that point to specific commits in your repository. Your deployment branch, usually called main, represents the content used to build your live documentation site. All other branches are independent of your live docs unless you choose to merge them into your deployment branch.

Branches let you create separate instances of your documentation to make changes, get reviews, and try new approaches before publishing. Your team can work on branches to update different parts of your documentation simultaneously without affecting what users see on your live site.

The following diagram shows an example of a branch workflow where a feature branch is created, changes are made, and then the feature branch is merged into the main branch.

We recommend always working from branches when updating documentation to keep your live site stable and enable review workflows.

Branch naming conventions

Use clear, descriptive names that explain the purpose of a branch.

Use:

• fix-broken-links
• add-webhooks-guide
• reorganize-getting-started
• ticket-123-oauth-guide

Avoid:

• temp
• my-branch
• updates
• branch1

Create a branch

Using web editor

1. Click the branch name in the editor toolbar.
2. Click New Branch.
3. Enter a descriptive name.
4. Click Create Branch.

Using local development

1. Create a branch from your terminal

   git checkout -b branch-name
   

   This creates the branch and switches to it in one command.

2. Push the branch to GitHub

   git push -u origin branch-name
   

   The -u flag sets up tracking so future pushes just need git push.

Save changes on a branch

Using web editor

Select the Save as commit button in the top-right of the editor toolbar. This creates a commit and pushes your work to your branch automatically.

Using local development

Stage, commit, and push your changes.

git add .
git commit -m "Describe your changes"
git push

Switch branches

Using web editor

1. Select the branch name in the editor toolbar.
2. Select the branch you want to switch to from the dropdown menu.

Unsaved changes are lost when switching branches. Save your work first.

Using local development

Switch to an existing branch:

git checkout branch-name

Or create and switch in one command:

git checkout -b new-branch-name

Merge branches

Once your changes are ready to publish, create a pull request to merge your branch into the deployment branch.

Delete a branch

After merging a branch, you can delete it to keep your repository organized.

Using web editor

After your pull request is merged, the web editor displays a notification that the branch has been merged. Click Delete branch to remove the branch from your repository.

You cannot delete the deploy branch or the repository’s default branch (usually main).

Using local development

Delete a branch locally and remotely:

# Delete the local branch
git branch -d branch-name

# Delete the remote branch
git push origin --delete branch-name

Use -D instead of -d to force delete a branch that hasn’t been merged.