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.
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 email@example.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 firstname.lastname@example.org:_My_User_Account_/foreman-documentation.git
Your local repository now has two remotes:
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,
git switchcommand changes the currently checked out branch, and
-ccreates 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,
$ 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
upstreambeing 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 fetchcommand downloads the tracked branch from your remote, and the
--alloption updates all branches simultaneously. This is necessary when working with additional branches. The
--pruneoption removes references to branches that no longer exist.
$ git fetch --all --prune
Pull possible changes from
upstream/masterinto your local
git pullcommand copies commits from the branch you're tracking into your current branch. This is used to "update" your local
masterbranch to the latest state of the
masterbranch 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
$ git switch master
Drop the last commit on
$ git reset --soft HEAD~1
Switch back to
my_featurebranch 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 amendto 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_Filewithout also committing it.)
Push your "change" to Github, using the
--forceoption 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
To restructure your work, rebase your branch and make changes as necessary. Rebasing to
mastermeans changing the parent commit of your first commit on your branch:
$ git rebase --interactive master
Replace the first word
pickto 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
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
-noption to limit the number of commits.
$ git log -n 5 3.3
Replicate changes by cherry-picking commits to your branch. The
-xoption 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
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
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.
Git for tech writers
Git is a tremendous help for technical writers. Not only can you use Git to version your own content, but you can actively collaborate with others.