A revert is (broadly speaking) an edit that reverses the actions of other editors. In that process a new version of the page is created.
This page serves as an overview of various types of reverts supported and recognized by MediaWiki, mainly for developers. It also discusses how to integrate extensions with revert-related mechanisms present in MediaWiki core.
There are three methods of performing reverts that are recognized by MediaWiki.
Undos are performed using the undo link that appears in page history, diff view, recent changes list and other places.
Undo links point to
undoafter parameters that specify which edits should be undone.
undo– the ID of the last revision being undone.
undoafter– the ID of the last "good" revision. The next revision will be the first revision being undone.
Undos can be performed through API using
undoafter parameters. Their behavior is the same as in
All revisions from
undoafter (exclusive) to
undo (inclusive) are reverted. EditPage attempts to merge the inverse of these edits with the sequence of all subsequent edits. If that is not possible, a regular edit form is displayed and the edit is not counted as an undo.
After that, the edit form is displayed to the user, where the resulting content can be further modified.
Since version 1.36, if the user performs any modifications to the content before saving, the edit is not marked as an undo. This is to prevent users from marking arbitrary edits as undos.
Other content types
If your extension implements a new ContentHandler, it can override the
getUndoContent method in order to customize how undos are handled by your content type.
Rollback can be performed using the rollback link that appears in page history, diff view, recent changes list and other places.
Rollback links point to
index.php?action=rollback with additional parameters for ensuring the correct set of changes is being rolled back.
See also: Manual:Parameters to index.php#rollback
Rollbacks can be performed through API using
action=rollback. Their behavior is the same as in
Rollback reverts the last edits made by the last editor of the page. This is a commonly useful scenario when dealing with vandalism, as usually all changes made recently by one user should be reverted.
The manual revert does not use any special UI or API, as it is inferred by the software automatically. Every time an edit is made, MediaWiki looks at a number of most recent revisions of the page (specified by
$wgManualRevertSearchRadius, 15 by default) and looks for the most recent revision with matching content. If such a revision is found, the edit is marked as a "manual revert", i.e. an edit restoring the page to an exact previous state.
The feature can be disabled entirely by setting
$wgManualRevertSearchRadius to zero.
- Manual revert:
Since version 1.36 additional data about the revert is saved with each tag in the
ct_params field of the
change_tag table. The data is the EditResult object associated with the edit (see the next section), encoded as JSON.
Accessing revert information in extensions
Version 1.35 introduced theclass that is constructed when saving an edit. This object encapsulates information about the effects of the edit in the context of its page's history, most importantly:
- whether the edit was a revert,
- which revert method was used,
- what is the "base" revision for this revert,
- which revisions were reverted.
This object is passed to extensions using the PageSaveComplete hook.
In version 1.36 a new change tag is introduced –
mw-reverted that is used to mark reverted edits.
Scheduling and execution
If your wiki has a busy job queue and you encounter significant delays between making reverts and the tag being applied, you may want to execute the job in a separate queue or prioritize it, depending on your setup. See Manual:Job queue for details.
Conditions for execution
The update will be scheduled after saving an edit if all of the following conditions are met:
- The edit is a revert of any type recognized by MediaWiki. See: #Revert types.
- The number of reverted edits is less or equal to
- The reverting revision itself is not marked as reverted or deleted.
- The edit is considered auto-approved, which can have different meanings depending on your setup:
- If you have patrolling enabled on your wiki through the
$wgUseRCPatrolconfiguration variable, auto-approval is equivalent to the edit being autopatrolled. Thus, only users with
autopatroluser right will have their reverted tag applied right away.
- If you have installed a content management extension such as FlaggedRevs it can tell MediaWiki if the edit is auto-approved. How exactly is this determined depends on the extension (see: #Extension integration).
- If you have patrolling enabled on your wiki through the
If the reverted tag update is stopped by the patrol subsystem or an extension, it can be later rescheduled when the edit is approved by a different user. In case of patrolling, this happens when the edit is patrolled. See the next section for details on how to integrate with this feature in extensions.
autopatroluser right to a wider group of users.
Extensions that involve some kind of revision approval mechanism can hook into the reverted tag feature to let MediaWiki know when to perform the reverted tag update.
The first part of this is the BeforeRevertedTagUpdate hook. It is called before the update is scheduled and extensions can use this hook to prevent the update from running if the edit is not considered auto-approved and needs further review.
If the update was stopped, it can be later rescheduled by the extension using the
- Approving a revision
$revertedTagUpdateManager = MediaWikiServices::getInstance()->getRevertedTagUpdateManager(); $revertedTagUpdateManager->approveRevertedTagForRevision( $acceptedRevisionId );
If you have installed the FlaggedRevs extension, the revert will be considered auto-approved if either:
- FlaggedRevs is configured to not be used on the page.
- The user has the
- The edit is a self revert.
- The edit is otherwise eligible to be autoreviewed.
If the revert was not auto-approved, it can be later approved by simply reviewing the edit.