As a technical writer working for [ATIX][1], my tasks include creating and maintaining documentation for [Foreman][2] at [github.com/theforeman/foreman-documentation][3]. 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][4] 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][5]. 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][3] 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][6] 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][7] 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][8] and [CONTRIBUTING.md][9] 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][3] 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][10]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:
- 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][3], 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
- 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`.
- 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.
### 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][11] 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][12] 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.
