Revision Retention

Description

WordPress keeps post revisions forever unless you set WP_POST_REVISIONS, and even then the only thing you can set is a count that applies to the whole site and only takes effect while a post is being saved. A site that has been running for a few years ends up with tens of thousands of revisions nobody will ever open, slowing down queries and padding out every backup.

This plugin gives revisions a retention policy instead:

• Always keep the newest few. A floor that is never crossed, however old those revisions are.
• Remove what is older than a threshold. Anything past the floor and past the age you pick, from a week up to five years.
• Set both per post type. Long history for posts, a short leash on pages, nothing at all for a custom post type that churns.
• Clean up what is already there. A scheduled sweep works through the site in batches, so an old site with a large wp_posts table is cleaned up over several quiet runs rather than one heavy one.

The two numbers work together

This is the part worth understanding, because it is what keeps the plugin safe to switch on:

• Always keep is a floor. The newest N revisions of a post are never deleted, whatever their age.
• Remove older than is a ceiling, and it only applies to what is left above the floor.

So a page that was last edited three years ago, with forty revisions and a policy of keep 5, remove older than 365 days, keeps its five most recent revisions and loses the other thirty-five. It does not lose its whole history just because all of it is old.

Setting Always keep to -1 means every revision is retained and that post type is never swept, whatever the age threshold says.

Autosaves are never touched. An autosave is somebody’s unsaved work rather than a point in the history.

Enable revisions where WordPress does not

Some post types ship without revision support, so nothing is recorded at all. The settings screen lists every eligible post type with a checkbox to switch revisions on for it. It applies from the next time such a post is saved.

On a schedule

The sweep runs in the background at an interval you choose. Every run books the next one itself: another batch in a minute while there is work left, or the next full run at your interval once the site is clean. A sweep that gets interrupted continues where it stopped instead of starting over.

There are also Preview and Run one batch now buttons on the settings screen. Preview reports what the policy would remove without deleting anything.

A log of every sweep

The log is on from the start, and every sweep that removes revisions gets an entry on the Logs tab: whether the schedule, somebody on the settings screen, or WP-CLI ran it, who that was, how many revisions it removed from how many posts, and per post type. A sweep spread over many batches is one entry. The tab shows them on a timeline, with a bar per day for the last month. Entries are kept for as long as you choose, from a week to a year, and older ones are deleted daily. Previews are never logged, and the log can be switched off on the Logs tab.

Each site keeps its own log, next to its own revisions. On multisite the network screen’s Logs tab shows every site’s log together on one timeline, with each entry naming the site it ran on and linking to that site’s own log.

From WP-CLI

# What is the policy, and what has it still got to do?
wp revision-retention status

# The rule and the stored revisions of every post type.
wp revision-retention post-types

# See what would go, without deleting anything.
wp revision-retention run --dry-run

# Apply the policy to pages only.
wp revision-retention run --post-type=page --yes

On multisite

The network admin sets the defaults for every site, under Network Admin → Settings → Revision Retention. A switch there decides whether sites may override them. When they may, each site’s own screen inherits every field it leaves empty and shows the network value behind it; when they may not, that screen reports the policy and nothing more.

Settings travel the other way too. Once you have a policy on one site that you want everywhere, Save as network default on that site’s screen makes it the default for the whole network and drops the site’s own copy, so the site simply inherits what it already had. Sites with settings of their own keep them; only the defaults underneath move. The button only appears for a network administrator, since it decides what every other site starts from.

When the network keeps the policy to itself, a site’s screen can still Preview — reading what the policy would take away costs nothing — but only a network administrator can actually sweep that site. Otherwise a network could switch the scheduled sweep off and a site administrator could still delete by hand, which is the opposite of what locking the policy is for.

The network screen can Preview every site, walking the whole network and reporting what the policy would remove without deleting anything, Sweep every site now, which does the same and deletes as it goes, site after site, with a progress bar and an entry in each site’s log, and Schedule a sweep on every site, which leaves the work to WP-Cron on each site instead. Both pass over the sites that have switched the sweep off. The sweep itself always runs per site, under whatever policy that site ends up with.

Its Logs tab brings the log of every site together, so you can see what was removed across the network, where, and by whom, without opening each site in turn.

For developers

// Never touch these posts, whatever the policy says.
add_filter( 'revision_retention_excluded_posts', fn( $ids ) => [ ...$ids, 42, 108 ] );

// Decide the rule for a post type in code.
add_filter( 'revision_retention_rule', function ( $rule, $post_type ) {
    return 'page' === $post_type ? new Retention_Rule( 20, 90 ) : $rule;
}, 10, 2 );

// Change which post types can have a policy at all.
add_filter( 'revision_retention_eligible_post_types', $callback );

Deletion goes through wp_delete_post_revision() rather than a bulk query, so post meta and term relationships are cleaned up the way WordPress expects and other plugins see the hooks they are listening for.

Development happens at github.com/acato-plugins/revision-retention.

Technical details