This post is part of my Git for Writers series, which I’m posting as an accompaniment to my Git Started: Git for Agile Writers workshop at the STC 2015 Summit in Columbus, OH. These posts expand on some of the ideas I’ll be presenting, since you can’t cram everything on such a large subject into one 45-minute workshop.
If you’ll be at the Summit, I look forward to seeing you there!
One of the most important reasons for Agile TechComm professionals to use Git is Git’s extensive set of archaeological commands. (For some more of the reasons why I think writers need Git, read this post.)
This post covers perhaps the most important of these commands, from an Agile writer’s perspective. “git diff” shows the difference between two items in Git. It’s the first line of defense when you’re asking “What changed?” (If you’re familiar with the Linux diff command, it’s basically the same thing, but for Git.)
It’s hard to say exactly what “git diff” shows the difference between, since its uses allow for many different comparisons:
- The difference between all of the files in two commits.
- The difference between a file in two commits.
- The difference between the current branch and the main repository.
- The difference between the current branch and another branch.
In various scenarios, each of these comparisons can be extremely helpful, but a few of them come up more often and are more important for Agile writers using Git for information gathering.
This comparison (of a single file in two commits) is one of the most useful for git archaeology. I use it multiple times a day, to find the changes that have been made during the development process.
Of course, this command won’t replace the value of talking to developers about their changes, but it can show you the direction development is moving in. It’s also very useful for formulating questions about work that’s taking place, and it can help you to pinpoint any interface text changes that you need to make.
Like most git commands, git diff has a laundry list of options. Some of them are more useful than others, but if you’re often in a time crunch, –name-only can be particularly helpful. It modifies the output to only show the names of the files that changed.
Of course, this requires some existing understanding of your codebase and its file structure to be really useful.
If you’re hunting for a particular change, the “pickaxe” (-S<string>) is useful. This option looks for changes that introduce or remove whatever you put in place of <string>.
Here, I used -SWORKSHOP to search for differences that included “WORKSHOP” in them.
If your needs are a little more complex, -G<regex> is quite similar, but allows you to use a regular expression rather than a literal string.
This post only scratches the surface of the options for this command, listing some of the uses that I’ve found to be most useful in an Agile environment. If you want to go into further depth, I highly recommend Pro Git (it’s free!). Of course, you can also run “git diff –help” to view the Git Manual for the command.