Some WordPress sites contain a lot of "noise" like log entries, results of security scans, cache items, etc. It is not uncommon that even a simple-looking website contains hundreds of thousands of rows in the database which is a big problem for staging, both from the usability and performance perspective.

Because of that, VersionPress.com uses ignore rules to filter such things out. We're gradually improving these rules so please let us know if you have a site that seems to transfer a lot of unnecessary items between staging and live.

Custom ignore rules

You can create a vp-ignore.json file in your site root to exclude certain items from staging.

Ignoring files

Let's say you have a custom backup folder at wp-content/my-backups:

You can exclude it from staging by creating a vp-ignore.json file at the site root (/var/www/html) with this content:

{
  "example.com": {
    "files": [
      "/wp-content/my-backups"
    ]
  }
}

When you create a staging site now, it will not contain the my-backups folder at all:

In the JSON:

• The top-level key (example.com above) is any string that makes sense to you. It is not actively used by the staging engine right now, however, if you know which plugin created the folder we recommend that you use its slug, it might be used in the future. For example, ignore rules for Akismet would be under the akismet key.
• The files key is an array of files and/or folders to ignore. Each path should start with a slash.

Ignoring database entities

Now let's say you have created a staging environment and when pushing live, you notice that there are options created by someplugin that you don't want to push:

You can ignore them by updating your vp-ignore.json file to contain this:

{
  "example.com": {
    "files": [
      "/wp-content/my-backups"
    ],
    "database": {
      "${prefix}options": [
        {"option_name": "someplugin_.*"}
      ]
    }
  }
}

In the new database section:

1. The table name can be prefixed, use ${prefix} placeholder to use your site's actual prefix.
2. Under each table, there is an array of column => regex pairs that define what to ignore.

With this, the push to live will exclude the options.

Ignoring whole tables

You can also ignore entire tables, or, more precisely, all rows from them by using the all-rows keyword. The tables themselves will still be created which is important for functionality of some plugins.

For example, most of Wordfence tables can be ignored like this:

{
  "wordfence": {
    "database": {
      "${prefix}wfBadLeechers": "all-rows",
      "${prefix}wfBlockedCommentLog": "all-rows",
      "${prefix}wfBlockedIPLog": "all-rows",
      "... etc. ...": "all-rows"
    }
  }
}

Complex example

The example below is taken from our "global" rules that are applied to each site. Your rules will typically be simpler.

{
  "core": {
    "database": {
      "${prefix}options": [
        {"option_name": "_transient_.*"},
        {"option_name": "_site_transient_.*"},
        {"option_name": "cron"},
        {"option_name": "cron_.*"},
        {"option_name": "db_upgraded"},
        {"option_name": "rewrite_rules"},
        {"option_name": "recently_edited"},
        {"option_name": ".*\\.lock"},
        {"option_name": "can_compress_scripts"},
        {"option_name": "auto_core_update_(notified|failed)"},
        {"option_name": "(auth_|secure_auth_|nonce_|logged_in_)(key|salt)"},
        {"option_name": "logged_in_key"},
        {"option_name": "logged_in_salt"},
        {"option_name": "theme_switched"}
      ],
      "${prefix}postmeta": [
        {"meta_key": "_edit_lock"},
        {"meta_key": "_edit_last"},
        {"meta_key": ".*\\.lock"},
        {"meta_key": "_pingme"},
        {"meta_key": "_encloseme"}
      ],
      "${prefix}usermeta": [
        {"meta_key": "session_tokens"},
        {"meta_key": "nav_menu_recently_edited"},
        {"meta_key": "wporg_favorites"},
        {"meta_key": ".*dashboard_quick_press_last_post_id"}
      ],
      "${prefix}post": [
        {"meta_key": "session_tokens"},
        {"meta_key": "nav_menu_recently_edited"},
        {"meta_key": "wporg_favorites"},
        {"meta_key": ".*dashboard_quick_press_last_post_id"}
      ]
    },
    "files": [
      "/.maintenance"
    ]
  },
  "wp-super-cache": {
    "database": {
      "${prefix}options": [
        {"option_name": "wpsupercache_start"},
        {"option_name": "wpsupercache_count"},
        {"option_name": "wpsupercache_gc_time"},
        {"option_name": "supercache_stats"},
        {"option_name": "supercache_last_cached"},
        {"option_name": "preload_cache_counter"},
        {"option_name": "wpsc_feed_list"}
      ]
    },
    "files": [
      "/wp-content/cache"
    ]
  }
}

JSON Schema

The platform validates the JSON you create and will display an error if it is not well-formed or doesn't validate against the following schema:

{
  "title": "VersionPress.com staging ignore rules",
  "$schema": "http://json-schema.org/draft-06/schema#",
  "type": "object",
  "properties": {
    "$schema": {}
  },
  "patternProperties": {
    ".+": {
      "type": "object",
      "description": "Plugin slug (or basically anything; not significant at runtime)",
      "properties": {
        "database": {
          "type": "object",
          "description": "Database entities to ignore",
          "patternProperties": {
            ".+": {
              "anyOf": [
                {
                  "type": "array",
                  "description": "Table name – (${prefix}options will be replaced with wp_options if your site's $table_prefix is wp_)",
                  "items": {
                    "type": "object",
                    "patternProperties": {
                      ".+": {
                        "description": "Column name => regex",
                        "type": "string"
                      }
                    }
                  }
                },
                {
                  "const": "all-rows"
                }
              ]
            }
          }
        },
        "files": {
          "type": "array",
          "description": "Paths to ignore. Must be relative to site root. E.g.:\n\n['/readme.txt', '/wp-content/cache']"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Applying rules in live vs. staging

You may have noticed how you can update vp-ignore.json in both live or staging environments, it is just a file in the site root after all. It is OK if the rules are momentarily different, they will always apply to "their" environment. For example, in the Ignoring database entities example above, the wp_options will be ignored just in the staging first. Then, after push, which will also synchronize the vp-ignore.json files, the options will be ignored in both environments.