> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Revision Limits

> Keep only the latest N versions of matching files and prune older ones to save storage.

Diversion stores every version of every file forever. For large binary files that change often -- game builds, textures, audio -- this adds up fast. A 500 MB texture saved every week is about 26 GB of history each year.

A **revision limit** tells Diversion to keep only the latest N versions of the files that match a pattern. Older versions are pruned in the background to free storage.

Unlike [`obliterate`](/advanced/obliterate), which removes **every** version of a file, a revision limit keeps the file and its most recent versions -- only the excess older versions are removed.

<Note>
  A "version" (also called a revision) is one committed state of a file. `--keep 3` means Diversion keeps the three most recent committed versions of each matching file and prunes anything older.
</Note>

<Warning>
  Pruning permanently deletes older file versions and cannot be undone. It runs automatically after every commit with no prompt or confirmation. Review a repo's rules with `dv prune list` before you rely on them.
</Warning>

## Usage examples

| File type                                     | Typical keep    |
| --------------------------------------------- | --------------- |
| Compiled assets (`.uasset`, `.pak`)           | Head only (`1`) |
| Large textures (`.psd`, `.tga`, `.exr`)       | Last `3`-`5`    |
| Audio / video (`.wav`, `.mp4`)                | Last `2`-`3`    |
| Build output directories                      | Head only (`1`) |
| Source code and config (`.cpp`, `.h`, `.ini`) | No limit        |

## Requirements

* You must be an [**organization admin**](/basic/access-levels#organization-level-access).
* Revision limits are not supported on repositories synced with Git.

## How it works

1. An admin adds one or more rules. Each rule is a path pattern plus a keep count (see [`dv prune`](/cmd-ref/prune)).
2. After every commit, Diversion checks the files that commit touched against the rules and prunes versions beyond the keep count.
3. Pruning runs in the background. It does **not** slow down the commit, and the person committing sees no prompt or warning.

Pruning is silent by design: the admin (or a Perforce import) sets the policy, and committers cannot override it. Review what a repo will prune with `dv prune list`.

### Keep counts

* `--keep <N>` -- keep the latest `N` versions (`1` to `999`). `--keep 1` keeps the head version only.
* `--keep all` -- keep every version (never prune). Use this to carve a path back out of a broader limit (partially negate); see [Rule order](#rule-order).

### Branch-safe counting

"Keep N" is counted **per branch**, not per repository:

* Every branch's head version is always kept.
* A file's stored bytes are deleted only when **no** kept version on **any** branch still needs them.

So a version shared across branches survives until the last branch that needs it prunes it. When in doubt, Diversion keeps a version longer rather than deleting one a branch still needs.

### What is never pruned

* **Drafts and shelves.** Uncommitted work and shelved changes are always preserved.
* **Every branch's head.** The latest version on each branch is always kept, even with `--keep 1`.

## Glob syntax

Patterns are **anchored to the repo root**. Always quote them so your shell does not expand the wildcards. This is the same pattern grammar as [`obliterate`](/advanced/obliterate#glob-syntax).

| Pattern                    | Matches                                             |
| -------------------------- | --------------------------------------------------- |
| `/....pak`                 | All `.pak` files anywhere in the repo               |
| `/Builds/....pak`          | All `.pak` files anywhere under `/Builds/`          |
| `/Assets/Textures/....exr` | All `.exr` files anywhere under `/Assets/Textures/` |
| `/Builds/...`              | Everything under `/Builds/`                         |
| `/Assets/hero.psd`         | One specific file                                   |

## Rule order

Rules are an **ordered list**. When more than one rule matches a path, the **last matching rule wins**. Adding a rule appends it to the end, so a later rule can override an earlier one.

Use this to keep everything under a subtree while limiting a wider pattern:

```bash theme={null}
# Keep 1 version of every .pak file...
dv prune add "/....pak" --keep 1
# ...except release builds, which keep every version.
dv prune add "/Releases/....pak" --keep all
```

`dv prune list` prints rules in this priority order.

## Managing rules

Use [`dv prune`](/cmd-ref/prune) to list, add, edit, and remove rules:

```bash theme={null}
dv prune list                              # show all rules, in priority order
dv prune add "/....psd" --keep 5           # keep the latest 5 versions of every .psd
dv prune set <id> --keep 3                 # change a rule's keep count
dv prune remove <id>                       # delete a rule
```

Adding a rule applies it to **future** commits. It does not prune versions that already exist beyond the new limit; those are pruned as later commits touch each file.

## Coming from Perforce

This is the Diversion equivalent of Perforce's `+S` / `+Sn` file type modifier, which keeps only the last N revisions of a file.

When you [import a Perforce depot](/coming_from_perforce#migration-options), your existing `+S` rules can be brought over as Diversion revision limits so retention carries across the migration. The import produces a review report of the translated rules for an admin to apply. **Contact the Diversion team** to run a Perforce import.

<Note>
  Diversion guarantees branch-safe counting by design. Perforce's `+S` behavior across branches changed between server versions and is not consistent -- Diversion always keeps every branch's head and never deletes a version another branch still needs.
</Note>

## Related

* [`dv prune`](/cmd-ref/prune) -- CLI reference for managing rules
* [Obliterate](/advanced/obliterate) -- permanently delete every version of a file
* [Storage](/concepts/storage) -- how Diversion stores and shares file versions
* [Coming from Perforce](/coming_from_perforce) -- migration guide