Learning the Basics of Git in Technical Writing

Today, Git is all the rage in the software world. It is a distributed version control system for tracking changes, and is widely used in today’s workflows where remote working is becoming the norm. Although mainly used by developers, many job descriptions for technical authors in the UK list knowledge of Git as a requirement.

I’ve found that using Git was quite tricky at first but was relatively straight-forward once I understood the concepts.  

Here are some aspects of Git that may help in your learning and use of this powerful version control system.

Git Provides a Unique Type of Document Management

I first learnt about the importance of document management in the context of files many years back. In a scenario where authors are working collaboratively, the golden rule is for you to update the file that is most up-to-date, and ensure that the other authors are updating from the same file. This was fairly easy to do if that single file was a 200 page word document. However, with Git you are not effectively managing files; you are managing “work” that can be shared across multiple files.

Git Responds to Specific Information you Provide

What Git does is determined by your instructions. Git can perform many powerful operations when given the correct commands. Thus, it is important to learn the key operations that Git can do. For example, Git add lets you stage a particular file. If you do not understand the concept of staging, then it can be difficult to perform tasks correctly.

When you use Git, you need to enter commands with the relevant flags. Thus, it is best suited for those who are good with the command line (I prefer Windows). But on a daily basis, you only need to use a few of the 170 commands that are part of Git.

Git Bases its Knowledge from Staging and Committing

When you understand how staging and commits work in Git, everything else seems to fall in to place.

At the heart of Git’s operation is the commit. A commit is a change to the Git database that Git knows about. That change could be to a single file or to multiple files that can take the form of an insertion, update, or a deletion of data. Your documentation can have new paragraphs, sections, or global CSS changes that are part of the same commit. You can set however many changes you want to commit. But for better tracking, you should minimise the number of changes within the commit.

Staging is the process that opens your work to a commit. If there is any change that you do not want to finalise, then it doesn’t have to be committed yet. But at least the change should be staged.

As I mentioned, Git is a service that responds to your instructions. Without you telling Git to stage a file, Git doesn’t know if that change exists. For example, if you have created a new file in Windows, Git has no idea that file exists before it is staged. And when you commit the file, Git knows that you have created a file of the specific name.

Renaming and Deleting a File

When you do a commit in Git, Git remembers the actions done on your “work”. It also remembers the name of the file associated with the commit. How Git responds to your “next action”, the rename, is determined by what it currently knows from the commit.

If a file is renamed, Git thinks that the file uses the old name. At this stage, according to Git, the file is “untracked” and “unstaged”. You will then need to stage and commit the name change for Git to know the new name. Similarly, if you have deleted a file, Git thinks that the file still exists if the change is not yet staged or committed.

The Man with Two Brains

Git, when installed on your computer, consists of a database that is a copy of everything in the remote Git location. Each repository is likened to a brain, and Git can be thought of as a person that has two brains. From the commits, Git knows the location of every file and changes within the local repository. However, Git also knows this information about the remote repository. Thus, Git lets you ensure that your local changes are in sync with the remote repository when you perform push and pull functions.

When you do a pull, Git copies the entire contents of the remote repository to the local repository. If any files are missing on your local computer, you may see an error. If any file contents differ from those in the remote repository, you may see merge conflicts.

Committing and Pushing Changes on a Regular Basis

You should commit and then push these changes to the remote location whenever you update your content. Both your local and remote repository need to end up with the same content. Thus, there should be the same number of commits in both repositories. You should not end up in a situation where your local repository has accumulated uncommitted changes.

You should also commit changes to your local repository to ensure it is up-to-date. The worse thing that can happen is pulling from a remote repository which results in your local content being overwritten.

Understanding Writing Restrictions

If updates to specific documents where you work can only be made by SMEs, you should ensure that none of these files contain your commits. This will prevent any unwarranted merge conflicts.

It is absolutely vital that you are informed of these restrictions in your workplace to prevent issues further down the line. If you want to make any changes to the content, these need to be made with the appropriate workflow outside of Git. For example, you may want to suggest changes over email.

Using Atlassian SourceTree

While Git is designed for the command line, SourceTree lets you conduct Git operations via the UI. There are many useful features in SourceTree including a visual map of the commit history of your database. The map also shows merges that took place on the remote repository.

Related Git Links and Book

Lastly, here are some useful links from:

Hackernoon

Atlassian

GitHub

Sarah Maddox

Tom Johnson

I can also recommend the book Git for Humans by David Demaree, which is available on Amazon.

Happy learning!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s