7 Git ideas for technical writers

As a technical author working for ATIX, my duties embody creating and sustaining documentation for Foreman at github.com/theforeman/foreman-documentation. Git helps me monitor variations of content material, and to collaborate with the open supply neighborhood. It’s an integral a part of storing the outcomes of my work, sharing it, and discussing enhancements. My fundamental instruments embody my browser, OpenSSH to hook up with Foreman situations, Vim to edit supply information, and Git to model content material.

This article focuses on recurring challenges when taking the primary steps with Git and contributing to Foreman documentation. This is supposed for intermediate Git customers.

Prerequisites

• You have put in and configured Git in your system. You should at the very least set your consumer title and electronic mail deal with.

• You have an account on github.com. GitHub is not an open supply mission itself, however it’s the positioning the place many open supply Git repositories are saved (together with Foreman’s documentation.)

• You have forked the foreman-documentation repository into your individual account or group (for instance, github.com/My_Name/foreman-documentation. For extra data, see A step-by-step guide to Git by Kedar Vijay Kulkarni.

• You have added your SSH public key to GitHub. This is critical to push your adjustments to GitHub. For extra data, see A short introduction to GitHub by Nicole C. Baratta.

Contributing to Foreman documentation

Foreman is an open supply mission and thrives on neighborhood contributions. The mission welcomes everybody and there are just a few necessities to make significant contributions. Requirements and conventions are documented within the README.md and CONTRIBUTING.md information.

Here are a number of the most frequent duties when engaged on Foreman documentation.

I wish to begin engaged on Foreman documentation

1. Clone the repository from github.com:

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

2. Rename the distant:

   $ git distant rename origin upstream

3. Optional: Ensure that your native grasp department is monitoring the grasp department from the foreman-documentation repository from the theforeman group:

   $ git standing

   This routinely begins you on the newest commit of the default department, which on this case is grasp.

4. If you would not have a fork of the repository in your individual account or group already, create one.

   Go to github.com/theforeman/foreman-documentation and click on Fork.

5. Add your fork to your repository.

   $ git distant add github git@github.com:My_Name/foreman-documentation.git

   Your native repository now has two remotes: upstream and github.

I wish to prolong the Foreman documentation

For easy adjustments similar to fixing a spelling mistake, you may create a pull request (PR) straight.

1. Create a department named, for instance, fix_spelling. The git swap command adjustments the at present checked out department, and -c creates the department:

   $ git swap -c fix_spelling

2. Make your change.

3. Add your change and commit:

   $ git add guides/frequent/modules/abc.adoc
   $ git commit -m "Fix spelling of existing"

   I can’t emphasise the significance of excellent Git commit messages sufficient. A commit message tells the mission maintainers what you’ve accomplished, and since it is preserved together with the remainder of the codebase, it serves as a historic footnote when somebody’s wanting again by way of code to find out what’s occurred over its lifespan.

4. Optional however advisable: View and confirm the diff to the default department. The default department for foreman-documentation known as grasp, however different initiatives could title theirs in a different way (for instance, fundamental, dev, or devel.)

   $ git diff grasp

5. Push your department to Github. This publishes your change to your copy of the codebase.

   $ git push --set-upstream github fix_spelling

6. Click on the hyperlink supplied by Git in your terminal to create a pull request (PR).

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

7. Add a proof on why the neighborhood ought to settle for your change. This is not needed for a trivial PR, similar to fixing a spelling mistake, however for main adjustments it is necessary.

I wish to rebase my department to grasp.

1. Ensure your native grasp department tracks the grasp department from github.com/theforeman/foreman-documentation, not foreman-documentation in your individual namespace:

   $ git swap grasp

   This ought to learn Your department is updated with 'upstream/grasp', with upstream being the title of your distant repository pointing to github.com/theforeman/foreman-documentation. You can evaluate your remotes by operating git distant -v.

2. Fetch potential adjustments out of your distant. The git fetch command downloads the tracked department out of your distant, and the --all choice updates all branches concurrently. This is critical when working with extra branches. The --prune choice removes references to branches that now not exist.

   $ git fetch --all --prune

3. Pull potential adjustments from upstream/grasp into your native grasp department. The git pull command copies commits from the department you are monitoring into your present department. This is used to “update” your native grasp department to the newest state of the grasp department in your distant (Github, on this case.)

   $ git pull

4. Rebase your department to “master”.

   $ git swap my_branch
   $ git rebase -i grasp

I’ve unintentionally dedicated to grasp

1. Create a department to save lots of your work:

   $ git swap -c my_feature

2. Switch again to the grasp department:

   $ git swap grasp

3. Drop the final commit on grasp:

   $ git reset --soft HEAD~1

4. Switch again to my_feature department and proceed working:

   $ git swap my_feature

I wish to reword my commit message

1. If you solely have one commit in your department, use git amend to vary your final commit:

   $ git commit --amend

   This assumes that you haven’t any different information added to your staging space (that’s, you didn’t run git add My_File with out additionally committing it.)

2. Push your “change” to Github, utilizing the --force choice as a result of the Git commit message is a part of your current commit, so that you’re altering the historical past in your department.

   $ git push --force

I wish to restructure a number of adjustments on a single department

1. Optional however strongly advisable: Fetch adjustments from Github.

   $ git swap grasp
   $ git fetch
   $ git pull

   This ensures that you simply straight incorporate some other adjustments into your department within the order they have been merged to grasp.

2. To restructure your work, rebase your department and make adjustments as needed. Rebasing to grasp means altering the mum or dad commit of your first commit in your department:

   $ git rebase --interactive grasp

   Replace the primary phrase choose to change the commit.

   • Use e to make precise adjustments to your commit. This interrupts your rebase!

   • Use f to mix a commit with its mum or dad.

   • Use d to utterly take away the commit out of your department.

   • Move the traces to vary the order of your adjustments.

     After efficiently rebasing, your individual commits are on high of the final commit from grasp.

I wish to copy a commit from one other department

1. Get the commit ID from a secure department (for instance, a department named 3.3), utilizing the -n choice to restrict the variety of commits.

   $ git log -n 5 3.3

2. Replicate adjustments by cherry-picking commits to your department. The -x choice provides the commit ID to your commit message. This is simply advisable when cherry-picking commits from a secure department.

   $ git swap My_Branch
   $ git cherry-pick -x Commit_ID

More ideas

At ATIX, we run a GitLab occasion to share code, collaborate, and automate assessments and builds internally. With the open supply neighborhood surrounding the Foreman ecosystem, we depend on Github.

I like to recommend that you simply at all times level the distant named origin in any Git repository to your inside model management system. This prevents leaking data to exterior providers when doing a git push primarily based on pure muscle reminiscence.

Additionally, I like to recommend utilizing a hard and fast naming scheme for remotes. I at all times title the distant pointing to my very own GitLab occasion origin, the open supply mission upstream, and my fork on Github github.

For foreman-documentation, the repository has a comparatively flat historical past. When working with a extra complicated construction, I have a tendency to think about Git repositories in a really visible method with nodes (commits) pointing to nodes on traces (branches) that doubtlessly intertwine. Graphical instruments similar to gitk or Git Cola can assist visualize your Git historical past. Once you’ve totally grasped how Git works, you may transfer on to aliases, in the event you desire the command line.

Before a giant rebase with plenty of anticipated merge conflicts, I like to recommend making a “backup” department you can rapidly view diffs in opposition to. Note that it is fairly exhausting to irreversibly delete commits, so mess around in your native Git repository earlier than making large adjustments.

Git for tech writers

Git is an incredible assist for technical writers. Not solely can you employ Git to model your individual content material, however you may actively collaborate with others.