# snapdir size

Report the logical and physical (deduplicated) byte size of a snapshot, a whole
store, or a local directory.

`size` is MANIFEST-BASED: it reads manifests only — never the content objects
they reference — so it is O(snapshots), not O(objects), and behaves the same
against a local directory or a remote store. Because objects are stored
uncompressed, the physical figure equals the real on-disk `.objects/` byte count
for everything the manifests reference.

## Two figures

| Figure | Meaning |
| --- | --- |
| **logical** | Σ of every file entry's size, with duplicates counted — the apparent content size of the tree(s). |
| **physical** | Σ of size over *unique* content checksums — the deduplicated on-disk footprint. |

`logical == physical` when nothing is shared; `logical > physical` shows how much
duplication content-addressing collapsed. `files` counts file entries; `objects`
counts unique checksums.

## Usage

```text
snapdir size [OPTIONS] [PATH]
```

`size` has three modes:

| Invocation | What it sizes |
| --- | --- |
| `snapdir size <dir>` | a local directory — computes its manifest in process, like `snapdir id <dir>` |
| `snapdir size --store <URI> --id <ID>` | a single snapshot in a store |
| `snapdir size --store <URI>` | the whole store — every snapshot, deduplicated across all of them (adds a `snapshots` count) |

### Arguments

| Argument | Description |
| --- | --- |
| `[PATH]` | A local directory to size instead of a store (like `snapdir id <dir>`). |

### Options

| Option | Description |
| --- | --- |
| `--store <URI>` | Store URI (`protocol://location/path`). Env: `SNAPDIR_STORE`. |
| `--id <ID>` | Snapshot ID to size. Omit (with `--store`) to size the whole store. |
| `--json` | Emit machine-readable JSON instead of the human-readable summary. |

The universal output flags (`-q`/`--quiet`, `--color`, `--no-progress`,
`--verbose`, `-h`, `-V`) are also accepted.

## Output

Human-readable, for a single snapshot or a directory:

```console
$ snapdir size ./project
logical    52 B   (4 files)
physical   52 B   (4 objects, deduplicated)
```

Whole store — a leading `snapshots` line is added and objects are deduplicated
across every snapshot, so `logical` can be much larger than `physical`:

```console
$ snapdir size --store s3://backups/prod
snapshots  37
logical    45 GB   (58214 files)
physical   9.8 GB   (12004 objects, deduplicated)
```

With `--json` (compact, one object per line). The `snapshots` key is present
only for a whole-store sweep:

```console
$ snapdir size --store s3://backups/prod --id 1220abc... --json
{"files":12345,"objects":9001,"logical_bytes":1288490188,"physical_bytes":882900992}

$ snapdir size --store s3://backups/prod --json
{"snapshots":37,"files":58214,"objects":12004,"logical_bytes":48318382080,"physical_bytes":10522669056}
```

Byte sizes are formatted base-1024 with `B`/`KB`/`MB`/`GB`/`TB`/`PB` units; the
`--json` `*_bytes` fields are always exact integers.

## Examples

Size a working directory before pushing it:

```console
snapdir size ./release-artifacts
```

Size one snapshot in a store by ID:

```console
snapdir size --store gs://inventory/dr --id 1220def...
```

Size a whole store and see how much dedup saved across every snapshot:

```console
snapdir size --store s3://backups/prod
```

Feed the exact figures to tooling — e.g. bytes reclaimed by deduplication:

```console
snapdir size --store file:///srv/store --json | jq '.logical_bytes - .physical_bytes'
```

## See also

- [`snapdir manifest`](snapdir-manifest.md) — the manifest `size` reads
- [`snapdir id`](snapdir-id.md) — the local-directory manifest id that `snapdir size <dir>` mirrors
- [`snapdir diff`](snapdir-diff.md) — manifest-only comparison, same read-only model