7 Git tips for technical writers

Follow along with this demo of how I use Git to write documentation for Foreman.

Person drinking a hat drink at the computer

Image by:

As a technical writer working for ATIX, my tasks include creating and maintaining documentation for Foreman at github.com/theforeman/foreman-documentation. Git helps me track versions of content, and to collaborate with the open source community. It's an integral part of storing the results of my work, sharing it, and discussing improvements. My main tools include my browser, OpenSSH to connect to Foreman instances, Vim to edit source files, and Git to version content.

This article focuses on recurring challenges when taking the first steps with Git and contributing to Foreman documentation. This is meant for intermediate Git users.

Prerequisites

You have installed and configured Git on your system. You must at least set your user name and email address.
You have an account on github.com. GitHub isn't an open source project itself, but it's the site where many open source Git repositories are stored (including Foreman's documentation.)
You have forked the foreman-documentation repository into your own account or organization (for example, github.com/_My_User_Account_/foreman-documentation. For more information, see A step-by-step guide to Git by Kedar Vijay Kulkarni.
You have added your SSH public key to GitHub. This is necessary to push your changes to GitHub. For more information, see A short introduction to GitHub by Nicole C. Baratta.

Contributing to Foreman documentation

Foreman is an open source project and thrives on community contributions. The project welcomes everyone and there are only a few requirements to make meaningful contributions. Requirements and conventions are documented in the README.md and CONTRIBUTING.md files.

Here are some of the most frequent tasks when working on Foreman documentation.

I want to start working on Foreman documentation

Clone the repository from github.com:

$ git clone git@github.com:theforeman/foreman-documentation.git
$ cd foreman-documentation/

Rename the remote:
```
$ git remote rename origin upstream
```
Optional: Ensure that your local master branch is tracking the master branch from the foreman-documentation repository from the theforeman organization:
```
$ git status
```
This automatically starts you on the latest commit of the default branch, which in this case is master.
If you do not have a fork of the repository in your own account or organization already, create one.

Go to github.com/theforeman/foreman-documentation and click Fork.
Add your fork to your repository.
```
$ git remote add github git@github.com:_My_User_Account_/foreman-documentation.git
```
Your local repository now has two remotes: upstream and github.

I want to extend the Foreman documentation

For simple changes such as fixing a spelling mistake, you can create a pull request (PR) directly.

Create a branch named, for example, fix_spelling. The git switch command changes the currently checked out branch, and -c creates the branch:
```
$ git switch -c fix_spelling
```
Make your change.
Add your change and commit:
```
$ git add guides/common/modules/abc.adoc
$ git commit -m "Fix spelling of existing"
```
I cannot emphasise the importance of good Git commit messages enough. A commit message tells contributors what you have done, and because it's preserved along with the rest of the codebase, it serves as a historical footnote when someone's looking back through code to determine what's happened over its lifespan. For more information on great git commit messages, see The seven rules of a great Git commit message by cbeams.
Optional but recommended: View and verify the diff to the default branch. The default branch for foreman-documentation is called master, but other projects may name theirs differently (for example, main, dev, or devel.)
```
$ git diff master
```
Push your branch to Github. This publishes your change to your copy of the codebase.
```
$ git push --set-upstream github fix_spelling
```

Click on the link provided by Git in your terminal to create a pull request (PR).

remote: Create a pull request for 'fix_spelling' on Github by visiting:
remote:      https://github.com/_My_User_Account_/foreman-documentation/pull/new/fix_spelling

Add an explanation on why the community should accept your change. This isn't necessary for a trivial PR, such as fixing a spelling mistake, but for major changes it's important.

I want to rebase my branch to master.

Ensure your local master branch tracks the master branch from github.com/theforeman/foreman-documentation, not foreman-documentation in your own namespace:
```
$ git switch master
```
This should read Your branch is up to date with 'upstream/master', with upstream being the name of your remote repository pointing to github.com/theforeman/foreman-documentation. You can review your remotes by running git remote -v.
Fetch possible changes from your remote. The git fetch command downloads the tracked branch from your remote, and the --all option updates all branches simultaneously. This is necessary when working with additional branches. The --prune option removes references to branches that no longer exist.
```
$ git fetch --all --prune
```
Pull possible changes from upstream/master into your local master branch. The git pull command copies commits from the branch you're tracking into your current branch. This is used to "update" your local master branch to the latest state of the master branch in your remote (Github, in this case.)
```
$ git pull
```

Rebase your branch to "master".

$ git switch my_branch
$ git rebase -i master

I have accidentally committed to master

Create a branch to save your work:
```
$ git switch -c my_feature
```
Switch back to the master branch:
```
$ git switch master
```
Drop the last commit on master:
```
$ git reset --soft HEAD~1
```
Switch back to my_feature branch and continue working:
```
$ git switch my_feature
```

I want to reword my commit message

If you only have one commit on your branch, use git amend to change your last commit:
```
$ git commit --amend
```
This assumes that you don't have any other files added to your staging area (that is, you did not run git add My_File without also committing it.)
Push your "change" to Github, using the --force option because the Git commit message is part of your existing commit, so you're changing the history on your branch.
```
$ git push --force
```

I want to restructure multiple changes on a single branch

Optional but strongly recommended: Fetch changes from Github.
```
$ git switch master
$ git fetch
$ git pull
```
This ensures that you directly incorporate any other changes into your branch in the order they've been merged to master.
To restructure your work, rebase your branch and make changes as necessary. Rebasing to master means changing the parent commit of your first commit on your branch:
```
$ git rebase --interactive master
```
Replace the first word pick to modify the commit.
- Use e to make actual changes to your commit. This interrupts your rebase!
- Use f to combine a commit with its parent.
- Use d to completely remove the commit from your branch.
- Move the lines to change the order of your changes.
  
  After successfully rebasing, your own commits are on top of the last commit from master.

I want to copy a commit from another branch

Get the commit ID from a stable branch (for example, a branch named 3.3), using the -n option to limit the number of commits.
```
$ git log -n 5 3.3
```
Replicate changes by cherry-picking commits to your branch. The -x option adds the commit ID to your commit message. This is only recommended when cherry-picking commits from a stable branch.
```
$ git switch My_Branch
$ git cherry-pick -x Commit_ID
```

More tips

At ATIX, we run a GitLab instance to share code, collaborate, and automate tests and builds internally. With the open source community surrounding the Foreman ecosystem, we rely on Github.

I recommend that you always point the remote named origin in any Git repository to your internal version control system. This prevents leaking information to external services when doing a git push based on pure muscle memory.

Additionally, I recommend using a fixed naming scheme for remotes. I always name the remote pointing to my own GitLab instance origin, the open source project upstream, and my fork on Github github.

For foreman-documentation, the repository has a relatively flat history. When working with a more complex structure, I tend to think of Git repositories in a very visual way with nodes (commits) pointing to nodes on lines (branches) that potentially intertwine. Graphical tools such as gitk or Git Cola can help visualize your Git history. Once you have fully grasped how Git works, you can move on to aliases, if you prefer the command line.

Before a big rebase with a lot of expected merge conflicts, I recommend creating a "backup" branch that you can quickly view diffs against. Note that it's pretty hard to irreversibly delete commits, so play around in your local Git repository before making big changes.