Diff and restore

Compare#

You can compare any two of these:

• a snapshot,
• the current site,
• an exported file.

In the dashboard, use Compare on the Snapshots screen (Swap sides flips the direction). From the terminal:

wp awc config diff 24                 # snapshot 24 against the current sitewp awc config diff 24 31              # two snapshotswp awc config diff settings.json   # a file against the current sitewp awc config diff old.json new.json --format=json

A snapshot id is a number; anything else is treated as a file path.

Reading a diff#

Each difference is one of three kinds: Added (set where there was nothing), Removed, or Changed. The plain-language view turns each into a sentence:

• Site title changed from 'A' to 'B'.
• Posts page was set to 7.
• Comment order was removed (it was 'asc').

Values are shortened to 80 characters. Booleans read on and off, and empty values read (empty) or (none). Nested settings that have a plain name show it (for example WP Mail SMTP's mail.from_email reads Sender email address); others show the setting's name followed by the inner names, such as myplug_settings › colors › header. The Raw JSON changes view gives the exact path, old value and new value for each entry.

Settings are compared as decoded values, never as raw stored text. Lists are compared as a whole; groups of values are compared key by key.

Secrets in a diff#

A redacted value is never counted as a difference. It is listed separately, with the sentence: "X is a secret. It is never exported or imported, and this site keeps its own value." The command line reports a count: 7 secret values are redacted and were not compared.

Environment settings in a diff#

If a file or snapshot you compare contains environment settings, the current site is read with them too, so a file made with --include-env compares fairly.

Restore: step by step#

Restoring a snapshot, and importing a file, run the same sequence:

1. Validate. The document goes through the importer checks described in Export and import. One invalid value stops everything, and nothing is changed.
2. Plan. For each source in the document the plugin compares your live (redacted) values with the incoming ones and builds a list of changes. This is the preview you see, and what --dry-run prints.
3. Skip what cannot be applied. Some sources are set aside, each with a stated reason. See below.
4. Warn about risky changes. Changing Anyone can register, New user default role, the email sender settings, or any ticked Other plugin and theme setting adds a "Security-sensitive change" warning to the preview. Nothing is written until you confirm these (in the dashboard, tick the box in the confirm dialog; from the terminal, add --accept-risky).
5. Stop if nothing differs. If there are no changes, nothing is written and no safety copy is made. The command says Nothing to change.
6. Take the safety copy. A pre-restore snapshot of the whole current site is stored. If this fails, the restore stops and nothing is changed.
7. Apply. For each source with changes, only the settings that differ are written. Settings missing from the file are left alone, not deleted. Secret markers are replaced by your site's own values, and nested secrets that the file does not mention are kept.
8. Clean up and report. After the Permalinks source changes, the stored rewrite rules are cleared so WordPress rebuilds them. You get a report of what was applied, unchanged and skipped, plus the number of the safety copy.

Two hooks let developers observe this: awc_scm_before_restore and awc_scm_after_restore. See For developers.

Settings that cannot be applied#

Some individual values are checked against your site as well as their type:

• New user default role must be a role that exists here and cannot manage the site. A role that has any of manage_options, edit_users, promote_users, install_plugins or activate_plugins is refused, so an untrusted file cannot turn open registration into administrator accounts. This is an error that stops the import.
• Pages and categories that do not exist here are skipped with a warning (see the importer checks).
• The theme logo: if the logo's media id does not exist on this site, your current logo is kept.

Skipped sources#

A source can be skipped as a whole. The restore continues with the rest and lists each skip with its reason:

The version check applies to plugin sources only, including toolkit.*. WordPress settings (core.*) and theme settings (theme.mods) are never version-gated. Two versions are compared by their leading number; if either version is missing or does not start with a digit, the check passes.

Other plugin and theme settings#

Other plugin and theme settings are never part of "restore everything" or a plain import. They are listed with the note "Other plugin and theme settings are only restored when you tick them." Tick the ones you want (or use --only / --all-other in the terminal), then confirm the risk.

Only the options the snapshot or file names are compared, so a restore never removes an option that exists on your site now. An option that exists now but is too large or in a format that cannot be read safely is left as it is, with a warning. A value of a different kind than the one on your site now (for example a list where the site has text) is not restored either.

What --force does#

--force (the REST parameter is force) applies a source despite a major version mismatch. It does not override a missing plugin, a not_applicable skip, a validation error or any other check. A warning is still shown for every source that was forced: "applying settings from a different major version because of --force."

Undo#

Every restore that changes something stores a safety copy first, with the label Before restoring snapshot #N (or Before CLI import or Before import for imports). Undoing is just restoring that copy.

Restoring a safety copy is treated specially, so that it really returns you to the earlier state:

• Options that did not exist when the copy was taken, because the change you are undoing created them, are removed. (Sources that are stored through a setter, such as theme settings, cannot delete keys.) Other plugin and theme settings are the exception: they are never deleted, so an option the restore created stays, and the undo says which.
• If the copy recorded environment settings (it does when you used --include-env), they are written back automatically, so the site URL and home URL return.

You can undo an undo the same way, because the undo itself makes a new safety copy.