February 28, 2021
Hot Topics:

10 Ways Git Version Control Can Streamline Your Writing Projects

  • By Jason Gilmore
  • Send Email »
  • More Articles »

Establishing a rigorous version control process is a standard part of any software project, and Git is a powerful system for enabling such version control. But Git's advantages extend beyond just software development. For instance, I use Git to manage all of my writing projects, including books and my articles published on Developer.com (including this one). Git offers writers a fantastic set of features for producing material in an impressively fast, efficient and organized manner. In this article I'll introduce you to 10 Git tips and tricks I regularly apply within my own writing projects! Even if you're using Git solely for software development, you'll still be able to apply these tips to your projects!

1. Stashing Incomplete Changes

Distractions are a standard part of any writing projects, and I often need to switch gears and work on another part of the project before completing the current task. For instance, suppose you were in the midst of working on a new section of documentation, and suddenly notice a rather misleading statement in the installation section. It would be a good idea to fix the error immediately and make those changes available to users, but you're not yet finished with the new section. What to do?

You can stash the section you're currently working on, fix and commit the error, and then apply the stash back to your working version. First, stash your changes:

$ git stash save

Next, fix the error and commit the changes. Then list your stashes:

$ git stash list
stash@{0}: WIP on master: c29f8cb Second commit

The {0} identifies the stash you'd like to apply. Incidentally, you can simultaneously maintain multiple stashes, each of which would be listed here if they existed. To apply the stash so you can continue working on the new section, use this command:

$ git stash apply stash@{0}

2. Tagging Releases

One of the really great advantages to managing large writing projects in Git is the ability to differentiate between developmental versions of the book using unique tags (of course, the same inherent advantages apply to software). For instance, if I want to designate a version of a book as alpha and make that version available to a set of reviewers, I can tag that version like this:

$ git tag -a v1.0a -m 'first alpha release'

You can then list tags using the tag command:

$ git tag

Cloning a certain tagged version of the project is also easy:

$ git clone /path/to/project/ /destination/path v1.0a

3. Working on Blue-Sky Chapters

Because I spend a good deal of time writing and revising books, ideas for new material are always percolating. Sometimes I know that I won't be able to incorporate a new chapter idea into a book for some time, maybe because the technology hasn't sufficiently matured. Yet I nonetheless want to create a chapter skeleton and occasionally add to that material as time arises, without incorporating this chapter to the ongoing set of general additions and improvements I'm making to the book. I can create a branch, which allows me to work on this chapter within the confines of my current project, while simultaneously not affecting the main development line (also known as the "master").

Suppose I considered eventually adding a new chapter about continuous integration to an existing book. I would start by creating a branch:

$ git branch continuous-integration

Then I would checkout that branch:

$ git checkout continuous-integration
Switched to branch 'continuous-integration'

At this point I can create a new chapter and work on it, committing changes until you want to turn my attention back to the main branch:

$ git checkout master
Switched to branch 'master'

If you're not familiar with development branches, try experimenting with them and listing the repository contents as you move from one branch to another. You'll see that it appears as if you're working on two separate projects, with the added luxury of managing them within one repository!

4. Merging Branches

When the time does come to incorporate an experimental chapter into the book's main development line, I'll want to merge the branches. For instance, to merge the continuous-integration branch into the master branch, I check out the master branch and then execute the following command:

$ git merge continuous-integration

5. Searching for Terms

When writing a large document over a period of several months it can be difficult to recall whether I formally introduced a particular topic. In order to avoid such redundancies, you can use Git's grep command to easily find all of the instances where a particular keyword appears within the repository:

$ git grep Phing
introduction.docbook:In Chapter 4 I'll introduce Phing
chapter04.docbook:Phing is an open source build tool
chapter07.docbook:Recall in Chapter 4 you were introduced to Phing

Based on the results, I apparently introduced Phing in Chapter 4. I need only a cursory glance at that chapter to ensure the introduction is indeed sufficient.

Originally published on https://www.developer.com.

Page 1 of 2

This article was originally published on December 19, 2010

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date