Version Control with Git for Docs

In this tutorial, you will learn about Version Control with Git for Docs. We cover key concepts, practical examples, and best practices to help you master this topic.

Git version control for documentation tracks every change, enables collaboration, supports branching and merging, and provides a complete history of who changed what and why.

What You'll Learn

You will learn the essential Git commands for managing documentation, how to set up a documentation Repository, and best practices for commit messages and branching.

Why It Matters

Without version control, documentation changes are invisible. You cannot see who made a change, when, or why. You cannot roll back a bad edit. You cannot collaborate without overwriting each other. Git solves all of these problems.

Real-World Use

Every documentation repository at DodaTech uses Git. When a developer updates Doda Browser configuration, they also update the documentation in the same commit. The full history shows exactly when docs changed alongside code.

flowchart LR
  A[Working Directory] -->|git add| B[Staging Area]
  B -->|git commit| C[Local Repository]
  C -->|git push| D[Remote Repository]
  D -->|git pull| A
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Setting Up a Documentation Repository

Initialize a repository for your documentation project:

mkdir project-docs && cd project-docs
git init
echo "node_modules/" > .gitignore
echo "public/" >> .gitignore
git add .
git commit -m "Initial commit: documentation scaffold"

Expected output:

Initialized empty Git repository in /Users/you/project-docs/.git/
[main (root-commit) a1b2c3d] Initial commit: documentation scaffold
 2 files changed, 3 insertions(+)

Essential Git Workflow for Docs

Adding and Committing Changes

# Check what changed
git status
# Stage a specific file
git add content/api/authentication.md
# Commit with a descriptive message
git commit -m "Update token expiry note in authentication guide"

Expected output:

On branch main
Changes not staged for commit:
  modified: content/api/authentication.md

[main a1b2c3d] Update token expiry note in authentication guide
 1 file changed, 2 insertions(+), 1 deletion(-)

Branching for Doc Changes

Create a branch for a documentation update:

git checkout -b docs/update-api-auth
# Make edits to docs
git add content/api/authentication.md
git commit -m "Fix curl example for new API version"
git push origin docs/update-api-auth

Expected output:

Switched to a new branch 'docs/update-api-auth'

Viewing History

# View commit history for a specific file
git log --oneline content/api/authentication.md

# See what changed in a specific commit
git show a1b2c3d

Expected output:

a1b2c3d Fix curl example for new API version
e4f5g6h Add authentication guide with curl examples

Writing Good Commit Messages for Docs

Follow the conventional commit pattern for documentation:

docs: add authentication guide for REST API

- Explain API key and OAuth2 authentication methods
- Include curl examples for each method
- Add error response reference table

Types for doc commits: docs for documentation changes, fix for correcting errors, chore for tooling changes.

Best Practices

Common Mistakes

1. Committing Large Binary Files

Binary files bloat the repository. Store images in a CDN and reference them by URL, or use Git LFS for large assets.

2. Writing Vague Commit Messages

"Updated file" tells future readers nothing. Explain exactly what changed and why.

3. Working Directly on Main Branch

Editing docs directly on main bypasses review. Always create a feature branch and open a Pull Request.

4. Ignoring .gitignore

Node modules, build output, and OS files should not be committed. A proper .gitignore prevents clutter.

5. Not Pulling Before Starting Work

Starting work on an outdated branch causes merge conflicts. Always pull the latest changes first.

6. Forgetting to Push

A commit on your local machine is not backed up. Push to the remote repository regularly.

7. Using Git Without a GUI

While the command line is powerful, tools like GitHub Desktop or GitKraken help non-developers manage Git workflows more easily.

Practice Questions

1. What command initializes a new Git repository?

git init

2. What is the difference between git add and git commit?

git add stages changes for commit. git commit saves the staged changes to the repository history.

3. Why should doc changes be made on a separate branch?

Branches isolate changes from the main codebase, enable pull request review, and allow multiple contributors to work simultaneously.

4. What makes a good commit message?

A good commit message explains what changed and why. Use the conventional commit format: type: description.

5. Challenge: Create a Git repository for a documentation project, make three commits with well-written messages, view the commit history, and create a branch for a new section of docs.

FAQ

Mini Project

Initialize a documentation repository, create a CONTRIBUTING.md file, commit it with a descriptive message, create a branch called docs/style-guide, add a STYLEGUIDE.md file, and merge the branch back to main.

What's Next

With Git under your belt, learn Markdown Basics for formatting documentation content. Then explore Static Site Generators.