Gemini 2.5 Flash × readme-writer

# snapdiff

A command-line tool to efficiently compare the contents of two directories, reporting added, removed, and changed files.

## Installation

`snapdiff` is a Python tool installable via pip.

It's recommended to install it within a virtual environment to avoid conflicts with system-wide packages:

```bash
# Create a virtual environment
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

# Install snapdiff
pip install snapdiff

# You can now run snapdiff
snapdiff --help

# To deactivate the environment
deactivate
```

Alternatively, for a global installation (not recommended for general use, but works):

```bash
pip install snapdiff
# Or, if you have multiple Python versions:
pip3 install snapdiff
```

## Usage

The basic usage is to provide two directory paths as arguments:

```bash
snapdiff <directory1> <directory2>
```

`snapdiff` will compare `directory1` against `directory2`.
- **Added files:** Files present in `directory2` but not in `directory1`.
- **Removed files:** Files present in `directory1` but not in `directory2`.
- **Changed files:** Files present in both, but with differing content.

### Options

```
Usage: snapdiff [OPTIONS] DIR1 DIR2

  Compares two directories and reports added, removed, and changed files.

Options:
  --ignore-hidden      Ignore hidden files and directories (starting with '.')
                       during comparison.
  --output [text|json]  Specify the output format.  [default: text]
  --depth N            Limit the recursion depth for directory traversal. 0 for
                       only top-level files, 1 for top-level and one level
                       down, etc.  [default: -1 (unlimited)]
  --help               Show this message and exit.
```

### Examples

**Basic comparison:**

```bash
snapdiff /path/to/old_data /path/to/new_data
```

**Compare, ignoring hidden files/directories:**

```bash
snapdiff project_v1 project_v2 --ignore-hidden
```

**Output results in JSON format:**

```bash
snapdiff /tmp/backup_monday /tmp/backup_tuesday --output json
```

**Limit comparison to top-level files only (depth 0):**

```bash
snapdiff my_photos_jan my_photos_feb --depth 0
```

**Combine multiple options:**

```bash
snapdiff src_prod src_dev --ignore-hidden --output json --depth 2
```

## Output Format

`snapdiff` supports two output formats: `text` (default) and `json`.

### Text Output (default)

The default text output provides a human-readable summary, categorized by file status.

```
--- snapdiff report ---
Directory A: /path/to/old_data
Directory B: /path/to/new_data

[ADDED FILES]
- new_feature.py
- assets/icon.png
- docs/installation.md

[REMOVED FILES]
- old_script.sh
- temp_files/log.txt

[CHANGED FILES]
- config.ini (content changed)
- src/main.py (content changed)
- images/logo.svg (content changed)
```

### JSON Output

The JSON output provides a structured, machine-readable format, suitable for scripting or integration with other tools. It will be an object containing three arrays: `added`, `removed`, and `changed`. Each array contains relative paths to the affected files.

```json
{
  "added": [
    "new_feature.py",
    "assets/icon.png",
    "docs/installation.md"
  ],
  "removed": [
    "old_script.sh",
    "temp_files/log.txt"
  ],
  "changed": [
    "config.ini",
    "src/main.py",
    "images/logo.svg"
  ]
}
```

## How it Works

`snapdiff` operates by recursively traversing both specified directories. For each file encountered:

1.  **File Listing:** It first builds a comprehensive list of all files in both directories, respecting the `--ignore-hidden` and `--depth` options.
2.  **Hashing:** To detect content changes, `snapdiff` calculates a cryptographic hash (e.g., MD5 or SHA256, depending on internal implementation) for the content of each file. This hash acts as a unique fingerprint for the file's content.
3.  **Comparison:**
    *   Files found only in `directory2` are marked as **Added**.
    *   Files found only in `directory1` are marked as **Removed**.
    *   Files found in both directories with the same relative path but different content hashes are marked as **Changed**.

This hash-based comparison allows for reliable detection of content modifications without having to perform a byte-by-byte comparison of potentially large files if their hashes already differ.