Diff

Unified diffs pack a lot of useful information into a small space and are worth learning to read. Here’s a diff (from git diff) which we’ll then unpack.

diff --git a/pset1/test020.c b/pset1/test020.c
index 0f59130..42e0ca5 100644
--- a/pset1/test020.c
+++ b/pset1/test020.c
@@ -2,7 +2,7 @@
 #include <stdio.h>
 #include <assert.h>
 #include <string.h>
-// test020: check for wild writes off the end of the allocated block.
+// test020: check for boundary write errors off the end of an allocated block.
 
 int main() {
     int *ptr = (int *) malloc(sizeof(int) * 10);

Each diff compares two files. We could call them the previous version and the current version, but it’s in some ways more useful to think of them as the left version and the right version.

• For diff -u FILE1 FILE2, FILE1 is the left version and FILE2 is the right version.
• For git diff, the current version in the version repository is the left version and the working copy is the right version. (Actually, the left version also includes changes in the staging area.)
• For git diff COMMIT, COMMIT is the left version and the working copy is the right version.
• For git diff COMMIT1 COMMIT2, COMMIT1 is the left version and COMMIT2 is the right version.

Unified diffs use - characters for the left version and + characters for the right version. It is common to use red for the left version and green for the right version, and your git diff may actually generate output colored this way by default.

Each diff’s header reports the left and right files. Since git diff compares two versions of the same file, rather than different files, it reports the filename prefixed with “a/” for the left file and “b/” for the right.

Diffs produced by git also report the left and right commit hashes.

Following a diff header are one or more diff sections, set off by @@ signs. A diff section shows a region of changes. Diff tries to report small, isolated sections when possible; if you change the first and last lines in a file, diff will report two sections, one at the beginning and one at the end. If you change every line in a file, though, you’ll get one huge section.

Each section header reports the first line number in the section. It gives a line number for both the left version and the right version, since one version might have different line numbers than the other.

Note that the - and + signs refer to versions, not, like, “line negative two.” The “,7”s mean that this section shows 7 lines of code for each version; if a section contains more lines for one version than for the other, these numbers will differ.

Finally, the meat of the diff consists of lines of text. Lines only in the left version start with -; lines only in the right version start with +. Lines in both versions start with a space. They’re provided for context to make the diff easier to read.

Putting it all together:

Options

• Use git diff -b to hide diffs that only change the amount of whitespace in a line.
• Use git diff -UN to get N lines of context per diff rather than three.