Git for writing documentation

Most developers these days are familiar with the Git version control system. It provides a powerful way to track changes over time and - when paired with a Git "forge" like GitHub or GitLab - makes it easier for developers to collaborate on software projects. But the power of Git also means it has a steep learning curve. Writers who aren't also software developers may find it difficult to get started, which might keep them from contributing to open source projects. This is a shame, because open source projects almost universally need help with their documentation.

But you don't have to know the full power of Git to be able to make meaningful contributions. In this article, you'll learn the basics of interacting with Git repositories from the command line. This is targeted explicitly at beginning Git users, and so does not include much in the way of choices or options. It's intended to give opinionated guidance, but there are other possible workflows. As you get more familiar with Git, you may find other ways that work best for you.

Prerequisites

To do anything else on this page, you'll need to have Git installed. If you're using Linux, it's probably pre-installed. If not, or if you're using another operating system, the Git documentation has installation instructions. This article assumes you have basic command line knowledge.

You'll also want to have a text editor, whether for the terminal (such as ViM or nano) or graphical (like Leafpad or Kate). It's important that this editor works with plain text. You don't want to use a word processor like LibreOffice; word processors add a lot of extra markup and metadata. This article does not cover using the text editor, but without making edits to files, the latter parts of the example won't be easy to follow.

Finally, you'll need an account on whatever Git forge you're using. This article uses an example repository hosted on GitHub. If the project you're contributing to uses a different Git forge, some of the instructions may be slightly different.

Before your first edit

When you first get started contributing to an open source project, you won't have write access to the project's documentation repository. You'll need to create your own copy, called a "fork." But first, you need to create a local copy of the project's repository.

1. Log in to GitHub in your web browser
2. Go to the repository (e.g. https://github.com/funnelfiasco/git-for-docs-writers). We will refer to this as the "upstream" repository from now on.
3. Click the Code button and select the HTTPS tab
4. Click the Copy button to copy the URL
5. In a terminal, go to the directory you want to keep your local copy of the repository in. For example: cd $HOME/docs
6. Run git clone <GIT URL> -o upstream. For example: git close https://github.com/funnelfiasco/git-for-docs-writers.git -o upstream. This downloads a copy of the repository with "remote" set to "upstream" into a directory with the same name as the repository.

Now you have a local copy of the repository, but since you don't have write access, you won't be able to upload your changes. So you have to create your fork. Again, these steps are for GitHub; other Git forges will be slightly different.

1. Go back to your web browser and visit the upstream repository.
2. Click the Fork button
3. On the "Create a new fork" page, leave the default settings as they are and click Create fork. Your browser will now take you to your forked copy of the upstream repository.

Now that you've created your fork, you need to add it to your local copy of the repository.

1. On your forked repository, click the Code button and select the HTTPS tab
2. Click the Copy button to copy the URL
3. In a terminal, go to the directory you cloned above (like cd $HOME/docs/git-for-docs-writers) if you're not already there
4. Run git remote add origin <HTTPS URL>. For example: git remote add origin https://github.com/YourUsername/git-for-docs-writers.git (replacing "YourUsername" with your GitHub username). This adds your fork as another remote.

Now you have your local repository set up and you're ready to make a contribution. The rest of the steps assume you're using a terminal and in the directory where you cloned the repository.

Before every contribution

Before you start making your contributions, you want to make sure you're up-to-date with the upstream repository. This means you are making changes to the latest version.

1. Ensure you're in the main branch with git checkout main
2. Get the upstream changes with git pull

Making a contribution

Now it's time to make the contribution you came here to make. You'll want to start by creating a new branch to do the work in. Here's a tip: branches are free. It's better to create a new branch even if you don't need it than to wish later that you had created a branch because you're trying to clean up conflicts. Make branches for even the most trivial contributions and you'll avoid that potential heartbreak.

git checkout -b <BRANCH_NAME> (where <BRANCH_NAME> is something like "issue8-fix_typos" or "add_git_tips_for_writers")

You can name the branch whatever you want. Descriptive names are good, especially if it's something you'll be working on over several sessions. If you're working directly on the upstream repository, using a unique and descriptive branch name helps other contributors know what your branch is.

If you're not sure what branch you're working in, you can check with git branch. Your current branch will have a * at the beginning of the line. If you need to switch to an existing branch, use git checkout <BRANCH_NAME>.

Now you can make whatever changes it is that you want. Fire up your favorite text editor and edit away. When you're done, it's time to commit the changes.

1. Stage the edited files with git add <NAMES_OF_FILES_YOU_EDITED> (for example: git add README.md)
2. Commit the files to the repository with git commit
3. Edit the commit message and quit the editor. If your system uses Vim as the default editor, type i to enter editing mode. When you're done writing your commit message, press the Escape key, type :wq, and hit Enter.

Good commit messages are helpful when someone (including future you) looks at the commit history to see what was done. A good commit message says what the commit does and why.

Here's another tip: keep commits atomic. Try to keep your commits related to a single logical change. This makes it easier to undo the commit later if needed. A "single logical change" may require editing multiple files, which should all be in one commit, but if you're adding unrelated content, do it separately.

Finally, it's time to push your changes from your local machine to the remote server and create the pull request.

1. Upload the changes to your fork with git push origin <BRANCH_NAME>
2. In your web browser, go to your forked repository (for example: https://github.com/YourUsername/git-for-docs-writers)
3. Follow the Git forge's instructions for creating a pull request. GitHub instructions are on the help site. GitLab uses the term "merge request."

Now you just have to wait for the project maintainers to approve your contribution and merge it into the main branch. If they ask you to make changes, you can make another commit in your branch and push it. The pull request will update automatically.

When you're ready to make another contribution, go back to the "Before every contribution" section. Happy contributing!