mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
2908750a1a
* Add git essentials page * update links * deployment branch naming * streamline intro
70 lines
3.9 KiB
Plaintext
70 lines
3.9 KiB
Plaintext
---
|
|
title: "Git essentials for the web editor"
|
|
sidebarTitle: "Git essentials"
|
|
description: "Understand the version control concepts behind the web editor."
|
|
keywords: ["git", "version control", "web editor", "branches", "commits", "pull requests", "PRs"]
|
|
---
|
|
|
|
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.
|
|
|
|
<AccordionGroup>
|
|
<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.
|
|
|
|
When you save changes, the web editor creates a commit.
|
|
</Accordion>
|
|
<Accordion title="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.
|
|
</Accordion>
|
|
<Accordion title="Deployment branch">
|
|
The branch that builds your live documentation site, typically called `main`. Changes merged into this branch automatically deploy to your site.
|
|
</Accordion>
|
|
<Accordion title="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).
|
|
</Accordion>
|
|
<Accordion title="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.
|
|
</Accordion>
|
|
<Accordion title="Conflict">
|
|
Occurs when two people change the same part of a file differently. The editor helps resolve any conflicts that occur on your branches.
|
|
</Accordion>
|
|
<Accordion title="Diff">
|
|
A comparison showing the differences between two versions of a file. When reviewing pull requests, diffs highlight exactly what changed.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## 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 |
|