GPT-5.6 Sol × readme-writer

# snapdiff

`snapdiff` is a Python command-line tool that compares two directories and reports added, removed, and changed files.

## Installation

Install from PyPI using pip:

```bash
python -m pip install snapdiff
```

Verify the installation:

```bash
snapdiff --help
```

## Usage

Compare two directories:

```bash
snapdiff PATH_A PATH_B
```

### Examples

Compare two directory snapshots using text output:

```bash
snapdiff ./before ./after
```

Ignore hidden files and directories:

```bash
snapdiff ./before ./after --ignore-hidden
```

Produce machine-readable JSON:

```bash
snapdiff ./before ./after --output json
```

Limit comparison to two directory levels:

```bash
snapdiff ./before ./after --depth 2
```

Combine options:

```bash
snapdiff ./before ./after --ignore-hidden --output json --depth 3
```

### Options

- `--ignore-hidden`: Exclude hidden files and directories, such as `.git` and `.env`.
- `--output json|text`: Select the output format. The default is `text`.
- `--depth N`: Limit recursive traversal to `N` directory levels.

## Output Formats

### Text

Text output groups relative file paths by status:

```text
Added:
  assets/logo.svg

Removed:
  docs/old-guide.md

Changed:
  README.md
  src/config.py
```

- **Added** files exist only in the second directory.
- **Removed** files exist only in the first directory.
- **Changed** files exist in both directories but have different contents.

### JSON

JSON output contains arrays of relative file paths:

```json
{
  "added": ["assets/logo.svg"],
  "removed": ["docs/old-guide.md"],
  "changed": ["README.md", "src/config.py"]
}
```

## How It Works

`snapdiff` recursively scans both directories and matches files by relative path. Paths found only in the second directory are marked as added, paths found only in the first are marked as removed, and matching paths with different file contents are marked as changed. Traversal and presentation are controlled by the selected command-line options.