feat: add git integration for comparing commits, branches, and working tree changes

Support comparing git refs with the same interactive TUI used for files and directories.
New CLI modes: no args (working tree vs HEAD), single ref (ref vs HEAD), two refs, and -C
flag for targeting any repo. Detail pane shows commit metadata with PR links on the root node.

Author: luispadron

README.md

@@ -4,9 +4,9 @@
   <img src=".github/assets/drift_logo.png" alt="Drift logo" width="700">
 </p>
 
-A **fast**, **interactive** file **comparison tool**. 
+A **fast**, **interactive** file **comparison tool**.
 
-Compare directories, archives, binaries, plists, and text files with a terminal UI or structured JSON output.
+Compare directories, archives, binaries, plists, text files, and git commits with a terminal UI or structured JSON output.
 
 [![asciicast](https://asciinema.org/a/858111.svg)](https://asciinema.org/a/858111)
 
@@ -51,6 +51,33 @@ drift -m binary MyApp-v1.0/MyApp.app/libcore.dylib MyApp-v2.0/MyApp.app/libcore.
 drift --json MyApp-v1.0 MyApp-v2.0
 ```
 
+### Git mode
+
+drift can compare git commits, branches, and working tree changes - bringing its interactive TUI to your git workflow.
+
+```sh
+# View uncommitted changes (staged + unstaged + untracked)
+drift
+
+# Compare a ref against HEAD
+drift HEAD~3
+drift main
+
+# Compare any two refs (commits, branches, tags)
+drift main feature-branch
+drift v1.0.0 v2.0.0
+
+# Target a different repo with -C
+drift -C ~/projects/my-app HEAD~1 HEAD
+
+# Force git mode when a ref collides with a file path
+drift --git main feature
+```
+
+When comparing git refs, the root node in the tree shows commit metadata including SHA, author, date, and links to the commit and pull request on GitHub.
+
+Auto-detection resolves arguments as git refs when they don't match filesystem paths. Use `--git` to skip path detection entirely.
+
 ## Agent skill
 
 drift ships a skill that gives AI coding agents native access to structured file comparison via `drift --json`. The skill is included in every [GitHub release](https://github.com/block/drift/releases).
@@ -79,6 +106,7 @@ drift auto-detects the comparison mode based on the inputs:
 
 | Mode | Inputs | What it shows |
 |------|--------|---------------|
+| **git** | Commits, branches, tags | File tree of changes between refs with commit metadata and per-file diffs |
 | **tree** | Directories, archives | File tree with added/removed/modified indicators, per-file diffs |
 | **binary** | Mach-O binaries | Sections, sizes, symbols, load commands. Requires `nm` and `size` |
 | **plist** | Property lists (.plist) | Structured key-value diff. Binary plists require `plutil` |
@@ -135,7 +163,7 @@ Every JSON result includes:
 | Field | Description |
 |-------|-------------|
 | `path_a`, `path_b` | The compared paths |
-| `mode` | Detected comparison mode (`tree`, `binary`, `plist`, `text`) |
+| `mode` | Detected comparison mode (`git`, `tree`, `binary`, `plist`, `text`) |
 | `root` | The diff tree - each node has `name`, `path`, `status`, `kind`, `size_a`, `size_b`, and optional `children` |
 | `summary` | Aggregate counts: `added`, `removed`, `modified`, `unchanged`, `size_delta` |
 
@@ -180,6 +208,7 @@ drift works on **macOS**, **Linux**, and **Windows**. Core features (directory/a
 
 | Tool | Used for | Availability |
 | --- | --- | --- |
+| `git` | Git mode (commit/branch/worktree comparison) | All platforms |
 | `nm`, `size` | Mach-O binary analysis | macOS (Xcode CLI Tools), Linux (binutils) |
 | `plutil` | Binary plist conversion | macOS only (XML plists work everywhere) |
 | `xclip` or `xsel` | Clipboard | Linux only (macOS and Windows work natively) |

cmd/drift/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"encoding/json"
+	"fmt"
 	"os"
 
 	"github.com/alecthomas/kong"
@@ -14,17 +15,25 @@ import (
 var Version = "dev"
 
 type cmd struct {
-	PathA   string           `arg:"" help:"First path to compare."`
-	PathB   string           `arg:"" help:"Second path to compare."`
+	PathA   string           `arg:"" optional:"" help:"First path or git ref to compare."`
+	PathB   string           `arg:"" optional:"" help:"Second path or git ref to compare."`
+	Dir     string           `short:"C" help:"Change to this directory before doing anything." default:"" type:"existingdir"`
 	Mode    string           `short:"m" help:"Force comparison mode (tree, binary, plist, text, image)." default:""`
+	Git     bool             `help:"Force git mode (compare refs, not paths)." default:"false"`
 	JSON    bool             `help:"Force JSON output."`
 	Version kong.VersionFlag `help:"Print version and exit."`
 }
 
 func (c *cmd) run() error {
+	if c.Dir != "" {
+		if err := os.Chdir(c.Dir); err != nil {
+			return fmt.Errorf("cannot change to directory %s: %w", c.Dir, err)
+		}
+	}
+
 	interactive := !c.JSON && goterm.IsTerminal(int(os.Stdout.Fd()))
 
-	result, err := compare.Compare(c.PathA, c.PathB, c.Mode)
+	result, err := c.resolve()
 	if err != nil {
 		return err
 	}
@@ -34,7 +43,7 @@ func (c *cmd) run() error {
 	}
 
 	// For standalone (non-tree) modes, automatically include the detail diff.
-	if result.Mode != compare.ModeTree {
+	if result.Mode != compare.ModeTree && result.Mode != compare.ModeGit {
 		detail, err := compare.Detail(result, result.Root)
 		if err != nil {
 			return err
@@ -48,6 +57,64 @@ func (c *cmd) run() error {
 	return outputJSON(result)
 }
 
+// resolve determines the comparison mode and returns the result.
+func (c *cmd) resolve() (*compare.Result, error) {
+	// No args: git working tree mode.
+	if c.PathA == "" && c.PathB == "" {
+		if !compare.IsGitRepo() {
+			return nil, fmt.Errorf("no arguments provided and not in a git repository\n\nUsage: drift <pathA> <pathB>")
+		}
+		return compare.CompareGitWorkTree()
+	}
+
+	// --git flag: treat args as git refs unconditionally.
+	if c.Git {
+		refA := c.PathA
+		refB := c.PathB
+		if refB == "" {
+			// Single arg with --git: compare ref against HEAD.
+			refB = refA
+			refA = "HEAD"
+		}
+		return compare.Compare(refA, refB, compare.ModeGit)
+	}
+
+	// Single arg: try as git ref, compare against HEAD.
+	if c.PathB == "" {
+		if !compare.IsGitRepo() {
+			return nil, fmt.Errorf("single argument requires a git repository\n\nUsage: drift <pathA> <pathB>")
+		}
+		if _, err := compare.ResolveGitRef(c.PathA); err != nil {
+			return nil, fmt.Errorf("%s is not a valid path or git ref", c.PathA)
+		}
+		return compare.Compare("HEAD", c.PathA, compare.ModeGit)
+	}
+
+	// Two args: check if both are filesystem paths first.
+	_, errA := os.Stat(c.PathA)
+	_, errB := os.Stat(c.PathB)
+
+	if errA == nil && errB == nil {
+		// Both exist on disk: use existing path comparison.
+		return compare.Compare(c.PathA, c.PathB, c.Mode)
+	}
+
+	// At least one doesn't exist as a path: try git refs.
+	if compare.IsGitRepo() {
+		_, gitErrA := compare.ResolveGitRef(c.PathA)
+		_, gitErrB := compare.ResolveGitRef(c.PathB)
+		if gitErrA == nil && gitErrB == nil {
+			return compare.Compare(c.PathA, c.PathB, compare.ModeGit)
+		}
+	}
+
+	// Fall through: report the original filesystem error.
+	if errA != nil {
+		return nil, fmt.Errorf("cannot access %s: %w", c.PathA, errA)
+	}
+	return nil, fmt.Errorf("cannot access %s: %w", c.PathB, errB)
+}
+
 type standaloneOutput struct {
 	*compare.Result
 	Detail *compare.DetailResult `json:"detail"`
@@ -64,7 +131,7 @@ func main() {
 	ctx := kong.Parse(
 		&cli,
 		kong.Name("drift"),
-		kong.Description("Compare files, directories, archives, and binaries."),
+		kong.Description("Compare files, directories, archives, binaries, and git refs."),
 		kong.UsageOnError(),
 		kong.Vars{"version": Version},
 	)

compare/binary.go

@@ -79,9 +79,17 @@ func extractFromBinary(source, relPath string) (map[string]bool, []sectionInfo,
 	return syms, secs, nil
 }
 
-// prepareBinaryPath returns a filesystem path to the binary. For archives,
-// it extracts the file to a temp location and returns a cleanup function.
+// prepareBinaryPath returns a filesystem path to the binary. For archives
+// and git sources, it extracts the file to a temp location and returns a cleanup function.
 func prepareBinaryPath(source, relPath string) (string, func(), error) {
+	if isGitSource(source) {
+		data, err := readGitContent(gitRef(source), relPath)
+		if err != nil {
+			return "", nil, err
+		}
+		return writeToTempFile(data)
+	}
+
 	info, err := os.Stat(source)
 	if err != nil {
 		return "", nil, err

compare/compare.go

@@ -17,6 +17,7 @@ const (
 	ModePlist  Mode = "plist"
 	ModeText   Mode = "text"
 	ModeImage  Mode = "image"
+	ModeGit    Mode = "git"
 )
 
 // Compare runs the appropriate comparison for the given paths and mode.
@@ -44,20 +45,28 @@ func Compare(pathA, pathB, mode Mode) (*Result, error) {
 		root, err = compareSingle(pathA, pathB, KindText)
 	case ModeImage:
 		root, err = compareSingle(pathA, pathB, KindImage)
+	case ModeGit:
+		root, err = compareGit(pathA, pathB)
 	default:
-		return nil, fmt.Errorf("unknown mode: %s (valid: tree, binary, plist, text, image)", mode)
+		return nil, fmt.Errorf("unknown mode: %s (valid: tree, binary, plist, text, image, git)", mode)
 	}
 	if err != nil {
 		return nil, err
 	}
 
-	return &Result{
+	result := &Result{
 		PathA:   pathA,
 		PathB:   pathB,
 		Mode:    mode,
 		Root:    root,
 		Summary: ComputeSummary(root),
-	}, nil
+	}
+
+	if mode == ModeGit {
+		result.Git = BuildGitMeta(pathA, pathB)
+	}
+
+	return result, nil
 }
 
 // compareSingle builds a single-node tree for standalone file comparison.

compare/detail.go

@@ -28,23 +28,30 @@ type DirSummary struct {
 // Detail computes an on-demand detail diff for a specific node.
 // It reads file content from the sources referenced in the result.
 func Detail(result *Result, node *Node) (*DetailResult, error) {
+	// Resolve source paths. For git mode, prefix with git:: so that
+	// readContent/contentHash/prepareBinaryPath dispatch correctly.
+	sourceA, sourceB := result.PathA, result.PathB
+	if result.Mode == ModeGit {
+		sourceA, sourceB = gitSourcePaths(result)
+	}
+
 	switch node.Kind {
 	case KindDirectory, KindDSYM:
 		return &DetailResult{Kind: node.Kind, Dir: summarizeDir(node)}, nil
 	case KindPlist:
-		diff, err := comparePlist(result.PathA, result.PathB, node.Path, node.Status)
+		diff, err := comparePlist(sourceA, sourceB, node.Path, node.Status)
 		if err != nil {
 			return nil, err
 		}
 		return &DetailResult{Kind: KindPlist, Plist: diff}, nil
 	case KindMachO:
-		diff, err := compareBinary(result.PathA, result.PathB, node.Path, node.Status)
+		diff, err := compareBinary(sourceA, sourceB, node.Path, node.Status)
 		if err != nil {
 			return nil, err
 		}
 		return &DetailResult{Kind: KindMachO, Binary: diff}, nil
 	case KindText:
-		diff, err := compareText(result.PathA, result.PathB, node.Path, node.Status)
+		diff, err := compareText(sourceA, sourceB, node.Path, node.Status)
 		if err != nil {
 			if errors.Is(err, ErrBinaryContent) {
 				// File was classified as text but contains binary data.
@@ -54,7 +61,7 @@ func Detail(result *Result, node *Node) (*DetailResult, error) {
 		}
 		return &DetailResult{Kind: KindText, Text: diff}, nil
 	case KindImage:
-		diff, err := compareImage(result.PathA, result.PathB, node.Path, node.Status)
+		diff, err := compareImage(sourceA, sourceB, node.Path, node.Status)
 		if err != nil {
 			return nil, err
 		}