git-didi 0.1.1
Compare diffs between two git ranges - a 'diff of diffs' tool for verifying rebases and tracking changes
License: MIT
Requires Python: >=3.10
Keywords: git, diff, rebase, cli

# git-didi

[![git-didi](https://img.shields.io/pypi/v/git-didi?label=git-didi)](https://pypi.org/project/git-didi/)

Compare diffs between two git ranges - a "diff of diffs" tool.

> **Demo Branches**: See [test scenarios](docs/test-strategy.md#proposed-test-branch-structure) for examples you can try. Test scenario 01 is live in this repo!

This tool is particularly useful for verifying rebases and merges, especially when complex conflict resolution was involved. It helps ensure that the actual changes in your branch remain approximately the same before and after rebasing onto a new upstream.

## Installation

```bash
pip install git-didi
```

Or with `uv`:

```bash
uv tool install git-didi
```

## Usage

### Common use case - checking a rebase

After fetching and rebasing your branch onto main:

```bash
git fetch
git rebase main
```

You can verify the rebase preserved your changes:

```bash
git-didi patch main@{1}..branch@{1} main..branch
```

This compares:
- **Left side**: Your changes before the rebase (`main@{1}..branch@{1}`)
- **Right side**: Your changes after the rebase (`main..branch`)

The `@{1}` syntax refers to the previous position in the reflog. If both refs moved exactly once during the rebase, `@{1}` will work. If you've done multiple operations, you may need `@{2}`, `@{3}`, etc. Use `git reflog` to find the right positions.

### Commands

#### `stat` - Compare diff stats

Compare `git diff --stat` output between two refspecs:

```bash
git-didi stat main..feature upstream/main..feature
```

Shows only the files where the diff statistics differ.

#### `patch` - Compare patches file-by-file

Compare patches between two refspecs, showing differences for each file:

```bash
git-didi patch main..feature upstream/main..feature
```

This shows a "diff of diffs" with sophisticated coloring to distinguish:
- Changes in the outer diff (what changed between the two versions)
- Changes in the inner diffs (the actual patches)

Options:
- `-U N` / `--unified N`: Set context lines (default: 3)
- `-q` / `--quiet`: Only list files with differences
- `-w` / `--ignore-whitespace`: Ignore whitespace changes
- `-M[n]` / `--find-renames[=n]`: Detect renames
- `-C[n]` / `--find-copies[=n]`: Detect copies
- `--color {auto,always,never}`: Control colored output
- `--pager {auto,always,never}`: Control pager usage

#### `commits` - Compare commits

Compare individual commits between two refspecs:

```bash
git-didi commits main..feature upstream/main..feature
```

First verifies that commits correspond (same count and messages), then shows per-commit differences.

#### `swatches` - Display color palette

Show color swatches demonstrating the diff-of-diffs coloring scheme:

```bash
git-didi swatches --color=always
```

### Filtering by path

All commands support filtering to specific paths:

```bash
git-didi patch main..feature upstream/main..feature -- src/
git-didi stat main..feature upstream/main..feature -- "*.py"
```

## Git Aliases

You can add these to your `~/.gitconfig` for convenient access:

```ini
[alias]
    didi = !git-didi
    gdds = !git-didi stat
    gddp = !git-didi patch
    gddc = !git-didi commits
```

Then use:

```bash
git didi patch main@{1}..branch@{1} main..branch
git gddp main..feature upstream/main..feature
```

## How it works

The tool automatically filters out spurious differences like git index SHAs that change even when the actual patch content is identical. This makes it easy to verify that a rebase or cherry-pick truly preserved your changes without introducing unexpected modifications.

When comparing patches, it uses a sophisticated 256-color palette to make nested diffs easy to read:
- Bright backgrounds for added/removed lines within the outer diff
- Dark backgrounds for context lines
- Mixed colors for lines that changed type (+ to - or vice versa)

## Try it yourself - Test Scenarios

This repo includes test branches demonstrating various rebase/merge scenarios. Try:

```bash
# Clone this repo
git clone https://github.com/ryan-williams/git-didi.git
cd git-didi

# Example: Clean rebase with disjoint changes
# Alice adds priority field, Bob adds JSON format - no conflicts!
git-didi patch tests/01-clean-disjoint/base..tests/01-clean-disjoint/alice \
               tests/01-clean-disjoint/bob..tests/01-clean-disjoint/alice-rebased-on-bob
# Output: "No differences in patches" ✓

# See what each developer changed
git log --oneline tests/01-clean-disjoint/base..tests/01-clean-disjoint/alice
git log --oneline tests/01-clean-disjoint/base..tests/01-clean-disjoint/bob

# Try the other direction
git-didi patch tests/01-clean-disjoint/base..tests/01-clean-disjoint/bob \
               tests/01-clean-disjoint/alice..tests/01-clean-disjoint/bob-rebased-on-alice

# Or verify a merge commit preserved both changes
git-didi patch tests/01-clean-disjoint/base..tests/01-clean-disjoint/alice \
               tests/01-clean-disjoint/merged^1..tests/01-clean-disjoint/merged
```

See [Test Strategy](docs/test-strategy.md) for details on the test scenarios and how to generate more.

## Development

```bash
# Clone and setup
git clone https://github.com/ryan-williams/git-didi.git
cd git-didi

# Setup with uv
uv sync --extra test

# Run tests
pytest tests/ -v

# Generate additional test scenarios
./scripts/generate-test-scenario.py 01-clean-disjoint

# Install locally
uv pip install -e .
```

## License

MIT License - see [LICENSE] for details.

[LICENSE]: LICENSE