> ## Documentation Index > Fetch the complete documentation index at: https://docs.basecut.dev/llms.txt > Use this file to discover all available pages before exploring further. # Snapshot Versioning > How Basecut manages multiple versions of snapshots and naming conventions Basecut automatically versions every snapshot you create, allowing you to maintain multiple point-in-time captures of your database and reference specific versions when restoring. ## How Versioning Works Every time you run `basecut snapshot create` with the same `--name`, Basecut creates a **new version** rather than overwriting the previous one. ### Generated Tags Each version is automatically assigned a unique, human-readable tag using an `adjective-animal` format: ``` brave-lion swift-falcon gentle-bison ``` These tags are generated by the Basecut API when you create a snapshot without providing an explicit tag. ### Storage Structure Snapshot references are name/tag based (`dev-seed:brave-lion`), while cloud storage objects are keyed by internal job IDs (for example `/snapshots//...`). Use CLI/API metadata (`snapshot list` and `snapshot inspect`) to map a name/tag reference to its storage location. *** ## Referencing Snapshots ### Using `:latest` The most common pattern—reference the newest version: ```bash theme={null} basecut snapshot restore dev-seed:latest --target "$BASECUT_DATABASE_URL" ``` **What happens:** 1. Basecut scans all versions of `dev-seed` 2. Selects the most recently created version 3. Restores that version **Use case:** Development workflows where you always want the freshest data. *** ### Using Specific Tags Reference an exact version by its unique tag: ```bash theme={null} basecut snapshot restore dev-seed:brave-lion --target "$BASECUT_DATABASE_URL" ``` **What happens:** 1. Basecut resolves `dev-seed:brave-lion` to an exact snapshot record 2. Restores that specific version 3. Fails if that tag doesn't exist **Use cases:** * Reproducing a bug with the exact data state * Rolling back to a known-good snapshot * Compliance/audit requirements for specific dates *** ### Implicit `:latest` Omitting the version defaults to `:latest`: ```bash theme={null} # These are equivalent basecut snapshot restore dev-seed --target "$BASECUT_DATABASE_URL" basecut snapshot restore dev-seed:latest --target "$BASECUT_DATABASE_URL" ``` *** ## Custom Tags You can override the automatic tag generation by providing your own tag using the `--tag` or `-t` flag: ```bash theme={null} # Create a snapshot with a custom tag basecut snapshot create --config basecut.yml --name dev-seed --tag v1-0-0 ``` **Referencing by custom tag:** ```bash theme={null} basecut snapshot restore dev-seed:v1-0-0 --target "$BASECUT_DATABASE_URL" ``` Custom tags must be lowercase alphanumeric with hyphens, starting and ending with an alphanumeric character. The tag `latest` is reserved. *** ## Version Management ### Listing Versions List snapshots from the CLI: ```bash theme={null} # List all snapshots (paginated) basecut snapshot list # Filter to one snapshot name basecut snapshot list --name dev-seed ``` For deeper details on one version: ```bash theme={null} basecut snapshot inspect dev-seed:brave-lion ``` ### Deleting Old Versions Delete snapshot metadata from the CLI: ```bash theme={null} basecut snapshot delete dev-seed:v1 --yes ``` For object cleanup, use storage lifecycle policies (recommended) or your storage provider CLI (`aws s3 rm`, `gsutil rm`). *** ## Best Practices ### 1. Use Descriptive Snapshot Names Names should indicate purpose, not just content: **Good:** ```bash theme={null} --name "dev-seed" # Clear: for development seeding --name "debug-user-12345" # Clear: debugging specific user --name "pre-migration-test" # Clear: testing before migration --name "qa-stable" # Clear: stable data for QA ``` **Avoid:** ```bash theme={null} --name "backup" # Vague: backup for what? --name "test" # Vague: test what? --name "data" # Vague: what data? ``` *** ### 2. Establish Naming Conventions **Pattern:** `-[-]` Examples: * `dev-seed` - Daily development data * `staging-smoke` - Smoke test data for staging * `prod-debug-issue-456` - Production debugging snapshot * `qa-regression-v2.0` - QA regression testing for v2.0 *** ### 3. Automate Snapshot Rotation Schedule snapshot creation in CI (see [CI/CD Integration](/workflows/ci-cd)) and configure storage lifecycle policies to automatically delete old versions. *** ### 4. Document Version Purpose Add metadata to your snapshot manifest for traceability: ```bash theme={null} # Capture git metadata basecut snapshot create \ --config basecut.yml \ --name "dev-seed" \ --git ``` **Result in manifest.json:** ```json theme={null} { "name": "dev-seed", "created_at": "2024-01-29T10:30:00Z", "git": { "commit": "a1b2c3d", "branch": "main", "repo": "github.com/myorg/myapp" } } ``` *** ### 5. Use Separate Snapshots for Different Use Cases Don't overload a single snapshot name: **Antipattern:** ```bash theme={null} # Same snapshot for everything --name "snapshot" # Used for dev, testing, debugging, etc. ``` **Better approach:** ```bash theme={null} # Separate snapshots by purpose --name "dev-daily" # Daily development refresh --name "ci-test" # CI/CD test suite --name "debug-prod-issues" # Production debugging --name "qa-regression" # QA regression suite ``` **Why:** Prevents accidental overwrites and makes version management clearer. *** ## Troubleshooting ### "Version Not Found" **Symptom:** ``` ✗ Error: version not found: dev-seed:old-tag ``` **Solutions:** 1. **List available versions:** ```bash theme={null} basecut snapshot list --name dev-seed ``` 2. **Check for typos in tag:** ```bash theme={null} # Tags are exact dev-seed:brave-lion # Correct dev-seed:brave-lions # Wrong (plural) ``` 3. **Use `:latest` instead:** ```bash theme={null} basecut snapshot restore dev-seed:latest --target "$BASECUT_DATABASE_URL" ``` *** ### "Multiple Versions Found" This shouldn't happen—Basecut resolves versions using unique snapshot tags and IDs. If you see this error, file a bug report. *** ## Next Steps Understand snapshot anatomy and structure Configure S3, GCS, or local storage Patterns for versioning in practice Complete command documentation