Git workflow for documentation contributors

Git is a distributed version control system that allows everyone to collaborate on the documentation project. Each contributor works on their own local copy of the repository and shares changes through a remote repository hosted on GitHub.

This page explains the Git workflow used in the documentation project and the common Git commands you will need.

How the workflow works

The documentation workflow follows a branch-based model. You never edit directly on the main branch. Instead, you create a separate branch for your changes, push it to GitHub, and open a pull request for review.

The typical workflow is:

Clone or pull — Get the latest version of the repository on your local machine.
Branch — Create a new branch for your topic.
Edit — Make your changes (add or update files, images, etc.).
Stage and commit — Save your changes locally with a descriptive message.
Push — Upload your branch to the remote repository on GitHub.
Pull request — Open a pull request on GitHub for the documentation team to review.

Step-by-step example

First-time setup

If you are contributing for the first time, clone the repository to your local machine:

git clone <repository_url>

This creates a local copy of the entire repository. You only need to do this once per repository.

Returning contributors

If you already have a local copy, make sure you are on the main branch and pull the latest changes before starting new work:

git switch main
git pull

Create a branch

Create and switch to a new branch for your topic:

git switch -c <branch_name>

For branch naming conventions, refer to the Branch naming convention section in the Quick Start guide.

Make your changes

Open the project in Visual Studio Code and edit or create the relevant files:

code .

Stage, commit, and push

Once you are satisfied with your changes, stage them, commit with a descriptive message, and push the branch to GitHub:

git add .
git commit -m "Add installation topic for Product X"
git push origin <branch_name>

After pushing, create a pull request on GitHub and assign a documentation team member for review.

Git command reference

Below is a quick reference of Git commands commonly used in the documentation process.

Command Description

Command	Description
`git clone <url>`	Create a local copy of a remote repository.
`git status`	Show the state of the working directory and staging area (tracked, untracked, and modified files).
`git add <file>`	Stage changes from the working directory for the next commit. Use `git add .` to stage all changes.
`git commit -m "<message>"`	Save all staged changes with a descriptive message.
`git pull`	Fetch and merge the latest changes from the remote repository into your local branch.
`git push origin <branch>`	Upload your local branch to the remote repository.
`git switch <branch>`	Switch to an existing branch.
`git switch -c <branch>`	Create a new branch and switch to it.
`git log`	View the history of commits in the repository.
`git diff`	Show differences between the working directory and the last commit.
`git restore <file>`	Discard uncommitted changes in a file, or unstage a staged file with `git restore --staged <file>`.
`git config --global --edit`	Open the global Git configuration file for editing.

git clone <url>

Create a local copy of a remote repository.

git status

Show the state of the working directory and staging area (tracked, untracked, and modified files).

git add <file>

Stage changes from the working directory for the next commit. Use git add . to stage all changes.

git commit -m "<message>"

Save all staged changes with a descriptive message.

git pull

Fetch and merge the latest changes from the remote repository into your local branch.

git push origin <branch>

Upload your local branch to the remote repository.

git switch <branch>

Switch to an existing branch.

git switch -c <branch>

Create a new branch and switch to it.

git log

View the history of commits in the repository.

git diff

Show differences between the working directory and the last commit.

git restore <file>

Discard uncommitted changes in a file, or unstage a staged file with git restore --staged <file>.

git config --global --edit

Open the global Git configuration file for editing.