Git essentials for the web editor

Understand the Git version control concepts behind the Mintlify web editor, including branches, commits, pull requests, merge workflows, and automatic sync.

Git lets you control and track changes to files. Git is the version control system of choice for docs-as-code workflows where you manage documentation the same way you would any other codebase.

The web editor handles Git operations for you. Understanding a few key concepts helps you get the most out of the editor and collaborate with your team.

What Git does for your docs

Git tracks every change made to your documentation. It records what changed, who changed it, when they changed it, and why. This means you can:

• See the full history of any page.
• Undo changes by reverting to a previous version.
• Work on updates without affecting your live site.
• Review changes before they go live.

Your documentation repository is the collection of files, and their history, that make up your documentation site. The web editor connects to this repository to read and update your content.

Key concepts

These are the Git concepts you’ll encounter most often when using the web editor.

Commit

A saved snapshot of your changes at a specific point in time. Each commit includes a message describing what changed and creates a permanent record in your project history.

When you save changes, the web editor creates a commit.

Branch

A separate line of work in your repository. Sometimes called a feature branch.

Your live documentation builds from a deployment branch, usually called main. Other branches let you work on changes independently. Nothing on a branch affects your live site until you merge it into your deployment branch with a pull request.

When you create a branch, the web editor creates a new branch in your repository. You can switch between branches from the branch dropdown in the toolbar.

Deployment branch

The branch that builds your live documentation site, typically called main. Changes merged into this branch automatically deploy to your site.

Pull request

A proposal to merge changes from one branch into another. Pull requests let your team review and discuss changes before they go live.

When you publish changes on a feature branch, the web editor creates a pull request. Your team reviews and merges the pull request in your Git provider (GitHub or GitLab).

Merge

Combining changes from one branch into another. After your team reviews and approves a pull request, merging the branch incorporates your changes into the deployment branch and publishes them.

Conflict

Occurs when two people change the same part of a file differently. The editor helps resolve any conflicts that occur on your branches.

Diff

A comparison showing the differences between two versions of a file. When reviewing pull requests, diffs highlight exactly what changed.

How the editor maps to Git

Every action you take in the web editor corresponds to a Git operation.

Your action in the editor	Git operation behind the scenes
Open a file	Fetch the latest version from your repository
Save changes	Create a commit, a snapshot of your changes in the project history
Create a branch	Create a branch, a separate line of work that doesn’t affect your live site unless you choose to publish it
Publish on your deployment branch	Push your commit directly, which triggers a deployment
Publish on a feature branch	Create a pull request, a proposal to merge your changes into the deployment branch

Automatic sync with Git

The web editor automatically keeps your documents in sync with your Git repository. When you open a page that has been updated in Git since your last edit, the editor fetches the latest version and merges the changes into your working document.

This means you don’t need to manually refresh or reload pages to see updates from teammates or CI pipelines that push directly to your repository. The editor handles this in the background using a three-way merge:

1. The editor compares the base version (the Git state when you last opened or synced the file), your current edits, and the latest version from Git.
2. Changes that don’t overlap are merged automatically.
3. Your unsaved edits are preserved alongside the incoming Git changes.

The editor syncs with Git each time a document is opened and periodically while it’s active. If the file hasn’t changed in Git, no sync occurs.