Skip to main content
You already know what a branch is conceptually — a separate workspace where you can make changes without affecting the live site. This lesson is about using branches in practice: when to create one, what to call it, and how to manage it through to completion.

​
When to create a branch

The rule is simple: any time you start a new piece of work, create a new branch. That includes small changes. It’s tempting to edit a single typo directly on main, but that bypasses the review step and skips the preview deployment. Even minor changes benefit from going through a pull request — it takes an extra thirty seconds and gives you a preview link to verify the change looks right before it goes live. The web editor handles this automatically — when you publish from the editor, Mintlify creates a branch and opens a pull request on your behalf. If you’re working locally with the CLI, you create the branch yourself before you start editing.

​
How to name a branch

Branch names should describe the work, not the person doing it. A name like update-authentication-guide tells your teammates what’s changing. A name like ethan-edits tells them nothing useful. A few conventions that work well for documentation:
  • Use lowercase letters and hyphens: add-quickstart-page, not Add Quickstart Page
  • Be specific enough to distinguish from other work: fix-api-reference-broken-links rather than just fix-links
  • Keep it short enough to type without pain — two to five words is usually right
You don’t need a naming convention that’s enforced by tooling. Something consistent enough that any teammate can glance at a branch list and understand what each one is for is sufficient.

​
The branch lifecycle

Every branch follows the same lifecycle:
1

Create the branch

Start from an up-to-date copy of main. If you’re working locally:
git checkout main
git pull
git checkout -b your-branch-name
This ensures your branch starts with the latest version of the live docs, which reduces the chance of conflicts later.
2

Make your changes and commit

Edit your files, then save your progress with a commit. Commit as you go — you don’t have to wait until everything is finished.
git add .
git commit -m "Add authentication quickstart"
Each commit is a checkpoint you can refer back to. A series of focused commits is easier to review than one large commit at the end.
3

Push and open a pull request

When you’re ready for review, push your branch to GitHub and open a pull request.
git push origin your-branch-name
GitHub will prompt you to open a PR. Mintlify automatically generates a preview deployment as soon as the PR is open.
4

Merge and clean up

Once the PR is approved and merged, delete the branch. It’s done its job, and leaving stale branches around makes it harder to see what work is actually in progress.GitHub offers a Delete branch button immediately after merging. One click and it’s gone.

​
Keep branches short-lived

A branch that stays open for a week is a branch that’s drifting further from main every day. The longer it lives, the more likely it is that someone else has merged conflicting changes. The fix is to keep branches small and focused. A branch that does one thing — adds one page, fixes one section, updates one set of links — can be opened, reviewed, and merged quickly. A branch trying to do everything takes longer to review and has more surface area for things to go wrong. If you find yourself working on a large restructuring project, break it into a sequence of smaller PRs. Each one should leave the docs in a better state than it found them, even if the full project isn’t finished yet. Next up: Preview deployments — how Mintlify generates a live preview for every pull request, and how to use it to catch problems before they reach users.