# Source: https://www.mintlify.com/docs/guides/git-concepts.md

> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Git concepts for documentation

> Learn version control and collaboration fundamentals for docs-as-code workflows.

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.

<Steps>
  <Step title="Use the web editor first.">
    The [web editor](/editor/index) 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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Core Git concepts

<AccordionGroup>
  <Accordion title="Branch">
    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.
  </Accordion>

  <Accordion title="Clone">
    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.

    ```bash  theme={null}
    git clone https://github.com/your-org/your-repo
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Conflict">
    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.
  </Accordion>

  <Accordion title="Deployment branch">
    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.
  </Accordion>

  <Accordion title="Diff">
    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.
  </Accordion>

  <Accordion title="Merge">
    Combine changes from one branch into another. Usually done via pull request after review to incorporate feature work into your deployment branch.
  </Accordion>

  <Accordion title="Pull">
    Get the latest changes from the remote repository to your local copy. Keeps you up to date with other people's work.

    ```bash  theme={null}
    git pull
    ```
  </Accordion>

  <Accordion title="Pull request">
    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.
  </Accordion>

  <Accordion title="Push">
    Send your local commits to the remote repository. This makes your changes available to others and can trigger automatic deployments.

    ```bash  theme={null}
    git push
    ```
  </Accordion>

  <Accordion title="Remote">
    A version of your repository hosted on a server. Your local repository connects to a remote repository to push and pull changes.
  </Accordion>

  <Accordion title="Repository">
    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.
  </Accordion>

  <Accordion title="Stage">
    Prepare specific changes to include in your next commit. Staging lets you organize changes into logical commits.

    ```bash  theme={null}
    git add filename.mdx
    ```
  </Accordion>
</AccordionGroup>

## How the web editor uses Git

The web editor connects to your Git repository through the [GitHub App](/deploy/github) or [GitLab integration](/deploy/gitlab) 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

<Tabs>
  <Tab title="Using web editor">
    1. Open file in the [web editor](https://dashboard.mintlify.com/editor).
    2. Make changes.
    3. Click **Publish**.
    4. Changes appear in the repository and deploy automatically.
  </Tab>

  <Tab title="Using local development">
    1. Pull the latest changes: `git pull`
    2. Edit file in your editor.
    3. Stage changes: `git add filename.mdx`
    4. Commit: `git commit -m "Update documentation"`
    5. Push: `git push`
    6. Changes deploy automatically.
  </Tab>
</Tabs>

### Work on a feature branch

<Tabs>
  <Tab title="Using web editor">
    <Note>
      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.
    </Note>

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

  <Tab title="Using local development">
    1. Create a branch: `git checkout -b feature-name`
    2. Make and commit changes.
    3. Push branch: `git push -u origin feature-name`
    4. Create a pull request.
    5. Merge the pull request when ready.
  </Tab>
</Tabs>

### Review changes before publishing

<Steps>
  <Step title="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.
  </Step>

  <Step title="Make your changes.">
    Edit files and commit changes to the feature branch.
  </Step>

  <Step title="Create a pull request.">
    Create a pull request to propose merging the changes on your feature branch into the deployment branch.
  </Step>

  <Step title="Review the diff.">
    Check your changes. The pull request shows line-by-line differences from the original version of the file.
  </Step>

  <Step title="Get team feedback.">
    Team members can comment on specific lines or overall changes. Make any changes and commit them to the feature branch.
  </Step>

  <Step title="Merge when approved.">
    Merge the pull request to publish changes to your live documentation.
  </Step>
</Steps>

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