Skip to main content
Git is a version control system that tracks changes to your documentation and enables team collaboration. With Git, you can see what changed over time in files, who made the changes, when they made changes, and why. Git also makes it easy to revert to previous versions of files if you need to undo changes. The web editor performs Git operations behind the scenes. With an understanding of Git, you can work more effectively with the web editor and collaborate with team members who use local development.

​
Why Git for documentation?

Git provides essential capabilities for managing documentation.
  • Version history: See what changed, when, and why for every file.
  • Collaboration: Multiple people can work on different parts simultaneously.
  • Safety: Experiment without breaking live documentation.
  • Review workflows: Team members can review changes before publishing.
  • Recovery: Undo mistakes or restore previous versions.

​
New to Git?

If you’re completely new to Git and version control, here’s a path to get started.
1

Use the web editor first.

The web editor handles Git operations automatically.
  • See any changes visually as you make them.
  • Create branches with one click.
  • Publish and create pull requests without using Git commands.
This lets you learn Git concepts without using the command line.
2

Learn by doing.

As you use the web editor, you’re using Git.
  • Save changes creates a commit.
  • Create branch creates a Git branch.
  • Publish opens a pull request for review.
3

Explore local development when it is useful.

You can manage your documentation entirely with the web editor and dashboard, but you can customize your workflow by working in your local environment.
  • Create and edit files in your favorite editor.
  • Use command line Git, GitHub desktop, or an extension in your editor.
  • Preview changes locally before publishing.
  • Integrate with other tools like support tickets, issue tracking, and design systems.

​
Core Git concepts

A branch points to a specific commit in your repository. Your live documentation builds from a deployment branch. You can have any number of other branches with changes that are not yet published to your live documentation. If you want to incorporate the changes from a branch into your live documentation, you can merge the branch into your deployment branch through a pull request.Use branches to work on changes without affecting your live documentation, safely experiment with new features, and get reviews before publishing.
Download a complete copy of a repository to your computer, including all files and full history. When you clone, you get everything needed to work locally.
git clone https://github.com/your-org/your-repo
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.
Occurs when two people change the same part of a file differently. Git asks you to manually choose which change to keep or combine both changes.
The primary branch of your project. Changes to this branch automatically publish to your documentation site. Often called main, but you can set any branch as your deployment branch.
A diff (or difference) shows the changes between two versions of a file. When reviewing pull requests, diffs highlight what is different from the original version of the file.
Combine changes from one branch into another. Usually done via pull request after review to incorporate feature work into your deployment branch.
Get the latest changes from the remote repository to your local copy. Keeps you up to date with other people’s work.
git pull
A way to propose merging your changes on a branch into your live documentation. Allows for review and discussion before changes go live. Commonly called a PR, and also called a merge request in GitLab.
Send your local commits to the remote repository. This makes your changes available to others and can trigger automatic deployments.
git push
A version of your repository hosted on a server. Your local repository connects to a remote repository to push and pull changes.
Your documentation’s source code with all the files, and their history, that make up the pages of your documentation site. The web editor connects to your documentation repository to access and modify content.
Prepare specific changes to include in your next commit. Staging lets you organize changes into logical commits.
git add filename.mdx

​
How the web editor uses Git

The web editor connects to your Git repository through the GitHub App or GitLab integration and automates common Git operations. When you:
  • Open a file: The editor fetches the latest version from your repository, ensuring you’re always working with up to date content.
  • Make changes: The editor tracks your changes as a draft that can become a commit when you’re ready to save your work.
  • Save changes: The editor makes a commit with your changes, preserving your work in the project history.
  • Create a branch: The editor creates a new branch in your repository that anyone with access to the repository can use to collaborate and review changes.
  • Publish on your deployment branch: The editor commits and pushes directly to your deployment branch, which publishes your changes immediately.
  • Publish on other branches: The editor creates a pull request, which allows you to get feedback from others before merging your changes into your deployment branch.

​
Common workflows

​
Publish directly to your deployment branch

  1. Open file in the web editor.
  2. Make changes.
  3. Click Publish.
  4. Changes appear in the repository and deploy automatically.

​
Work on a feature branch

To create pull requests from the web editor, you must have a branch protection rule enabled that requires pull requests before changes can merge into your deployment branch. Without branch protection rules, changes on branches merge to your deployment branch when published.
  1. Create branch from the branch dropdown in the editor toolbar.
  2. Make and save changes on the branch.
  3. Click Publish to create a pull request.
  4. Merge the pull request when ready.

​
Review changes before publishing

1

Create a feature branch.

Work on changes in a branch separate from your deployment branch so that you can share and review the changes before publishing.
2

Make your changes.

Edit files and commit changes to the feature branch.
3

Create a pull request.

Create a pull request to propose merging the changes on your feature branch into the deployment branch.
4

Review the diff.

Check your changes. The pull request shows line-by-line differences from the original version of the file.
5

Get team feedback.

Team members can comment on specific lines or overall changes. Make any changes and commit them to the feature branch.
6

Merge when approved.

Merge the pull request to publish changes to your live documentation.

​
Git best practices

Every team develops their own workflows and preferences, but these are some general best practices to get started.
  • Write descriptive commit messages: Be specific about what changed using active language. Fix broken link in API docs is more informative than update page.
  • Use descriptive branch names: Branch names should explain the purpose the branch. Use informative names like update-api-reference instead of generic names like temp or my-branch.
  • Keep branches focused: Keep the changes on a branch focused on a specific task or project. This makes reviews easier and reduces conflicts.
  • Delete branches after merging: Delete branches when you no longer need them to keep your repository tidy.
  • Pull before you push: Always pull the latest changes before pushing to avoid conflicts. The web editor does this automatically.
  • Review your own changes first: Check the diff before creating a pull request.