Revision

In Drupal, saving a change to a revisionable item, such as a node, can add a new revision instead of overwriting the old text. The item keeps its ID, while each revision gets its own revision ID; on a node it also records the user who saved it, the time and an optional log message. One revision is the default revision that visitors see.

How revisions work in Drupal 11

An entity type opts in to revisions. Revisionable entities implement RevisionableInterface. Its setNewRevision() forces the next save to create a new revision, and isNewRevision() reports whether one will be created. isDefaultRevision() tells you if the entity is the default revision, and isLatestRevision() if it is the newest. Without a pending draft, both point to the same revision. With Content Moderation, a draft can be the latest revision while an older published one stays the default.

Entities that log their revisions also implement RevisionLogInterface, which stores the revision author, the creation time and a log message. NodeInterface extends both interfaces.

On the node edit form, the Revision information section holds a Create new revision checkbox and a Revision log message field. The checkbox is not shown for a new node, and the log message appears when the box is checked. A content type sets the default: under Structure › Content types, edit the type, open Publishing options and check or uncheck Create new revision. The type's default value is on.

The Revisions tab of a node lives at /node/{node}/revisions. It lists each version with its date, author and log message, marks the current one as Current revision, and offers Revert (or Set as current revision for a version newer than the current one) and Delete. These actions follow the permissions View all revisions, Revert all revisions and Delete all revisions, or the matching per-type permissions such as Article: Revert revisions. Each also requires access to view, edit or delete the item itself.

Example

In code, create a revision explicitly before you save:

$node->setNewRevision(TRUE);
        $node->setRevisionLogMessage('Updated the pricing table.');
        $node->setRevisionUserId(\Drupal::currentUser()->id());
        $node->save();

The edit form does the same work for editors when they leave Create new revision checked.

Common mistakes

• Turning off Create new revision. The save then updates the current revision instead of adding one, so the previous text is not kept.
• Leaving the log message empty. The Revisions tab shows the message under each entry. Without it, nobody can tell what changed.
• Expecting a revert to erase later versions. Revert saves a copy of the old revision as a new one, with the log message "Copy of the revision from" followed by the original date.
• Expecting to delete the current revision. Core refuses it.

For marketing and content teams

Revisions are your undo history for content. Write a short log message on every meaningful edit, so a colleague can find the version to restore. The core Revisions tab shows when and by whom, not what changed. The contributed Diff module adds highlighted word-level changes between revisions.

Sources

• RevisionableInterface, Drupal API
• RevisionLogInterface, Drupal API
• RevisionableStorageInterface, Drupal API
• ContentEntityForm, Drupal core source (11.4.x)
• NodeController, Drupal core source (11.4.x)
• NodeRevisionRevertForm, Drupal core source (11.4.x)
• Node routing, Drupal core source (11.4.x)
• Node permissions, Drupal core source (11.4.x)
• NodeType entity, Drupal core source (11.4.x)
• Node type form, Drupal core source (11.4.x)
• Drupal.org: Diff project