# History

snapdir records where snapshots have been written and how they relate, building a
lightweight history you can query without opening any store by hand. Three
commands cover the common questions:

- **`snapdir locations`** — *where* have snapshots been recorded? (which
  directories and stores)
- **`snapdir revisions`** — *which snapshots* exist at a given location?
- **`snapdir ancestors`** — *how did we get here?* (a snapshot's ancestor IDs and
  their locations)

These read snapdir's catalog of recorded activity, so they answer questions about
snapshots you have created, pushed, fetched, or pulled.

## List where snapshots live with `snapdir locations`

`snapdir locations` lists the directories and stores where snapshots have been
recorded — your inventory of every place snapdir knows about:

```sh
snapdir locations
```

Use it to discover the `--store` URIs and paths you can then drill into with
`revisions`. See [`snapdir locations`](../reference/snapdir-locations.md).

## List the snapshots at a location with `snapdir revisions`

`snapdir revisions` lists the snapshot IDs created on a single location — a store
URI or an absolute path. Point it at one of the locations from the previous
command:

```sh
snapdir revisions --location s3://my-bucket/snapshots
```

This is the catalog of IDs you can hand to [`snapdir pull`](pushing-pulling.md),
[`snapdir fetch`](../reference/snapdir-fetch.md), or
[`snapdir checkout`](../reference/snapdir-checkout.md). See
[`snapdir revisions`](../reference/snapdir-revisions.md).

## Trace lineage with `snapdir ancestors`

`snapdir ancestors` lists a snapshot's ancestor IDs together with the locations
that hold them. It answers "what came before this snapshot, and where can I get
it?" — useful for auditing provenance or finding a known-good earlier state to
restore:

```sh
snapdir ancestors --id "$id"
```

Combine it with `revisions` and `locations` to navigate from "I have this ID" to
"here is its lineage and exactly which store still has each ancestor." See
[`snapdir ancestors`](../reference/snapdir-ancestors.md).

## A typical investigation

```sh
# 1. Where has snapdir recorded snapshots?
snapdir locations

# 2. Which snapshot IDs exist at one of those locations?
snapdir revisions --location s3://my-bucket/snapshots

# 3. Trace one snapshot's lineage and where its ancestors live.
snapdir ancestors --id "$id"

# 4. Restore the one you want.
snapdir pull --store s3://my-bucket/snapshots --id "$id" ./restored
```

## Where to go next

- [Pushing and pulling](pushing-pulling.md) — act on the IDs you discover here.
- [Stores](stores.md) — the locations these commands enumerate.
- [Syncing](syncing.md) — replicate a discovered snapshot between stores.
- Reference: [`snapdir locations`](../reference/snapdir-locations.md),
  [`snapdir revisions`](../reference/snapdir-revisions.md),
  [`snapdir ancestors`](../reference/snapdir-ancestors.md).