Core Git concepts
Repository
Repository
Your documentation’s source where all files and their history are stored. The web editor connects to your repository to access and modify content.
Commit
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.
Branch
Branch
A branch points to a specific commit in your repository. Your live documentation is built 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.
Deployment branch
Deployment branch
The primary branch of your project that your live documentation content is built from. Changes to this branch are automatically published to your documentation site. Often called
main, but you can set any branch as your deployment branch.Pull request
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.
Diff
Diff
A diff (or difference) shows the changes between two versions of a file. When reviewing pull requests, diffs highlight what has been added, removed, or modified, making it easy to identify what changed.
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 can be used by anyone with access to the repository so they can 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.
Git best practices
Every team will develop their own workflows and preferences, but these are some general best practices to get you started.- Write descriptive commit messages: Be specific about what changed using active language.
- Use descriptive branch names: Branch names should explain the work being done and be meaningful to someone who is looking at the branches in your repository.
- Keep branches focused: Keep the changes on a branch focused on a specific task or project.
- Delete branches after merging: Delete branches when you no longer need them to keep your repository tidy.