This is a fairly short, but informative, manual for a powerful command in the git arsenal. At its simplest the manual explains the following uses of git-diff:

1. Show changes between the working tree and the index (or another tree).

   AKA What you could tell git to add to the staging area for a commit.

   git diff
   

2. Show changes between the index and tree.

   AKA Show what is staged for the next commit.

   git diff --cached HEAD
   

3. Show changes between two trees.

   AKA Show difference in between commits

   # Show diff for the last few commits to where our branch is now.
   git diff HEAD~3 HEAD
   
   # For ranges
   git diff 9a29ab57 HEAD
   git diff 9a29ab57..HEAD
   

4. Show changes between two blob objects.

   AKA diff specific files.

   # Show changes to the config.toml file in the last 3 commits.
   git diff HEAD~3..HEAD -- ./config.toml
   

5. Show changes between two files on disk.

   AKA Show difference in your working tree, to what’s in a commit.

   # What has changed about these files.
   git diff HEAD -- ./config.toml
   git diff HEAD~3 -- ./blog.org
   

The way I wrote these here is close to how they’re written in the manual. Understanding git-diff is aided by understanding the flow of git commits and objects; concepts like the index (staging area), the working tree, and references. I suggest reviewing the gittutorial manuals to brush up on these concepts if you need to.

Some other highlights of the manual:

• In depth examples of diff output formats.
• Options like --stat and --shortstat for at a glance change information.
• --ignore-all-space for ignoring whitespace changes.
• in the weeds info about diff algorithm options.
• Some options that really only exist for writing scripts against.

Thanks for reading this manual review! Be well.