Git concepts for documentation
Learn Git version control fundamentals for docs-as-code workflows, including repositories, branches, commits, and pull request collaboration.
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.
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.
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.
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
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 and turns them into a commit when you 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 lets you get feedback from others before merging your changes into your deployment branch.
Common workflows
Publish directly to your deployment branch
- Open file in the web editor.
- Make changes.
- Click Publish.
- Changes appear in the repository and deploy automatically.
- Pull the latest changes:
git pull - Edit file in your editor.
- Stage changes:
git add filename.mdx - Commit:
git commit -m "Update documentation" - Push:
git push - Changes 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.
- Create branch from the branch dropdown in the editor toolbar.
- Make and save changes on the branch.
- Click Publish to create a pull request.
- Merge the pull request when ready.
- Create a branch:
git checkout -b feature-name - Make and commit changes.
- Push branch:
git push -u origin feature-name - Create a pull request.
- Merge the pull request when ready.
Review changes before publishing
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.
Make your changes.
Edit files and commit changes to the feature branch.
Create a pull request.
Create a pull request to propose merging the changes on your feature branch into the deployment branch.
Review the diff.
Check your changes. The pull request shows line-by-line differences from the original version of the file.
Get team feedback.
Team members can comment on specific lines or overall changes. Make any changes and commit them to the feature branch.
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 docsis more informative thanupdate page. - Use descriptive branch names: Branch names should explain the purpose of the branch. Use informative names like
update-api-referenceinstead of generic names liketempormy-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.