Version History & Rollback

Every file write is automatically tracked with an immutable version history. You can view, restore, and roll back files at any time - no manual snapshots needed.

Commands

gipity file versions

List the version history of any file. Shows version numbers, timestamps, sizes, and sources.

gipity file versions src/index.html

gipity file restore

Switch a file to any version - older or newer. No data is lost; all versions are preserved.

gipity file restore src/index.html 2

gipity file rollback

Restore files and folders under a path to their state at a given point in time. Supports scoping to a specific directory and recursive/non-recursive modes.

gipity file rollback 2026-04-08T14:30:00Z                                   # entire project
gipity file rollback 2026-04-08T14:30:00Z --path src/components             # one folder, recursive
gipity file rollback 2026-04-08T14:30:00Z --path src --no-recursive         # direct children only
gipity file rollback latest                                                  # undo previous rollback

After a restore or rollback, gipity sync pulls the result into your local tree, and gipity deploy dev ships it.

How It Works

• Every file write creates an immutable version with a timestamp
• gipity file restore switches which version is active - all versions are preserved
• gipity file rollback derives the project state at any point in time from the version history
• Rollback handles both files (version-based) and folders (timestamp-based)
• Files created after the target time are removed; files that existed are restored
• All operations are wrapped in a transaction - atomic and safe

When to Use

• User says "undo that" → gipity file versions + gipity file restore for one file
• User says "go back to before I changed everything" → gipity file rollback with a datetime
• Something broke after a series of changes → gipity file rollback to before the changes
• Compare what changed → gipity file versions shows the full timeline per file

Retention policy (how long history is kept - and billed)

Version history is not kept forever. Each account has a retention policy with two bounds, and a version is pruned when it hits either one first:

• Age - versions older than N days are dropped.
• Copies - only the newest M versions of each file are kept.

The current version of every file is always kept, no matter how old - retention only trims old history, never live content, so a file you haven't touched in months is never lost.

Retention is enforced once a day by a cleanup pass that runs right before the storage meter, so the account is billed on its post-cleanup footprint. Storage is billed on physical bytes (retained versions included), so keeping less history costs less.

Defaults and limits (per plan)

• Free: 3 days / 10 copies.
• Pro: 90 days / 100 copies.

The plan sets the maximum a user may keep (and the default when they subscribe). A user can dial their own retention down from that cap to store less and pay less - never above the plan cap.

Telling the user their current policy

gipity storage retention reports the effective retention (days and copies kept, whichever comes first, and the plan maximum). That's how to answer "what's my version retention?" or "how long are my old versions kept?".

Seeing what's using the space

When an account is at or over its storage quota, find out where the space went before suggesting anything:

• CLI: gipity storage usage - billed bytes against the quota, the live-vs-version-history split, how much deduplication saved, and the biggest projects. Add --json for a machine-readable form.
• API: GET /users/me/storage.

Two figures matter and they are not the same. Billed is physical bytes: retained versions included, deduplicated blobs counted once - that's what the quota is enforced against. Live is just the current version of each file. A big gap between them means version history (or a large retention setting), not live content, is what's filling the account - so trimming retention is the fix, not deleting files.

Per-project numbers are live bytes only: dedup and history can't be attributed to a single project, so they won't sum to the billed total.

When the account is over quota

An over-quota write fails with a storage-quota error. Freeing space always works: delete files that are no longer needed, or keep less history (below). Upgrading only helps if the user's plan isn't already the one with the largest storage grant - credit packs do not raise the storage cap, so telling a top-plan user to buy credits is a dead end. The error text itself only suggests an upgrade when a bigger plan actually exists; follow its lead rather than reflexively recommending a purchase.

Changing it

Retention is a user-owned account setting - don't change it silently on their behalf. Explain the trade-off (less history = smaller storage bill, but shorter rollback reach) and point them at a surface that edits it:

• CLI: gipity storage retention (view), gipity storage retention --days <n> --count <n> (set), gipity storage retention --reset (back to the plan default).
• Monitor dashboard: Data > Files shows the policy with editable day/copy fields; Data > Browse shows a file's versions and restores one.
• API: GET /users/me/retention (view) and PATCH /users/me/retention { days, count } (adjust; a value above the plan cap is rejected, null resets a field to the plan default).