Skip to content

movefile.yml configurations explained

Jump to bottom Edit New page
Alessandro Fazzi edited this page Feb 13, 2022 · 24 revisions

Table of Contents generated with DocToc

First of all: movefile.yml is a YAML file. If you really have no idea take a look at this cookbook. It is abused in the ruby world, but YAML is used as well in the PHP frameworks world.

Just some notes before the rude doc

  1. space indentation delines the data structure! It's not optional nor coincidental!

  2. Wordmove's configuration file naming is valid in different flavours:

    • movefile.yml (default)
    • movefile.yaml
    • movefile (backward compatibility)
    • Movefile (backward compatibility ref)

If this is clear, let's go.

Doctor

The doctor command will harldy try to do formal validation on your movefile.yml. Please, use it when something blows up, at least as source of information to report an issue on the tracker.

First level keys: the environments

global:
  ...
local:
  ...
production:
  ...

These are the default first level keys and denotes your environments. global and local are mandatory. global is not really an environment, but is the place where we put options which change global behaviours. production is a convention for naming the remote env, but you can rename it as you like:

global:
  ...
local:
  ...
mycoolremotehost:
  ...

You can add as many new environments as you need:

global:
  ...
local:
  ...
test:
  ...
production:
  ...

More about environments can be found in the wiki article Multiple environments explained

Global options

global:
  sql_adapter: "wpcli"

mandatory

@since 2.1.0

sql_adapter introduces support to wp-cli's search-replace command as DB adapter. If you want to switch back to the old built-in adapter, you can set this option to default.

Funny is that default adapter is no more the default, but it retains its old naming. Sorry for the confusion.

No futher options could be passed to wp command through Wordmove. We use wp as per https://codex.wordpress.org/Changing_The_Site_URL#wp-cli, adding the —all-tables, --allow-root options and --path flag.

You can still use a wp-cli.yml config file as per WP-CLI documentation: since we're simply invoking your locally installed wp command, it will search for its own config.

You'll see the exact executed command in STDOUT

Note about the --path flag

@since 5.1.0

Wordmove tries to support a lot of development configurations and practices. Some scaffolds consist in exhotic dirtrees, some practices require to work within a theme/plugin folder, and so on. Wordmove will invoke the wp command from the path wordmove self was invoked, and this could lead WP-CLI to some confusion about where the WP path actually is.

This is the behaviour Wordmove has in order to programmatically choose the --path flag to pass to wp command:

  1. If you have a wp-cli.yml aside of movefile.yml and if wp-cli.yml has a path key configured, Wordmove will read and use it
  2. Else if you have a wp-cli.yml somewhere else, but still reachable by WP-CLI's internal searching logic, and it has a path key defined, then Wordmove will read and use it.
  3. If none of the above, then Wordmove will use its own wordpress_path config as --path for WP-CLI.

Per environment options: local

vhost

local:
  vhost: "http://localhost:8080"

mandatory

vhost is the url you use to get to your site. Keep in mind that if you install wordpress in subdirectories, the subdirectory should be part of the vhost. Most of the time - if not always - this should match

wp option get home

Please note that you could omit the trailing slash unless you're sure about a different neeed.

wordpress_path

local:
  wordpress_path: "/home/me/dev/site"

mandatory

Is simply the absolute path of you installation. With or without heading slash should work the same.

An aknowledged limitation is that wordmove doesn't correctly manage spaces in this path; shuold happens you have a space here, you have to manually escape, e.g.:

local:
  wordpress_path: "/User/user/Local\ Sites/mysite"

paths

paths:
  wp_content: "wp-content-custom"
  wp_config: "wp-config-custom.php"
  uploads: "wp-content-custom/uploads"
  plugins: "wp-content-custom/plugins"
  mu_plugins: "wp-content-custom/plugins"
  themes: "wp-content-custom/themes"
  languages: "wp-content-custom/languages"

optional

With this option you can customize Wordpress internal paths if you put/name them in non standard ways. This must be configured in movefile.yml for both local and remote environments; for example, staging and production.

Paths configured in local section will tell wordmove where to find and to put files in your local environment.

database

local:
  database:
    name: "mydatabase"
    user: "root"
    password: "toor"
    host: "localhost"
    port: 3306
    mysqldump_options: "--max_allowed_packet=50MB" # Only available if using SSH
    mysql_options: --protocol=TCP # mysql command is used to import db

mandatory keys: name, user, password, host

@since 3.0.0 database.charset option is no more supported. Pass the '--default-charecter-set' flag into database.mysqldump_options or to database.mysql_options instead, if you need to set the same option.

Here we point to our local database; I think it's self-explaining. In other situations you can alter port to suite your needs, otherwise we'll use the default as per the above snippet.

You can pass as a string any mysqldump accepted option inside the mysqldump_options key.

You can pass as a string any mysql accepted option inside the mysql_options key.

mysqldump_options: "--max_allowed_packet=50MB --ignore-table=dbname.wp_cf7dbplugin_submits --ignore-table=dbname.wp_cf7dbplugin_st"

mysqldump_options and mysql_options will be passed to the command line as they are; this means that you must provide adequate escaping, for example if you have spaces in paths, just as you'd do on the command line; e.g.:

mysqldump_options: '--socket "/Users/fuzzy/Library/Application\ Support/Local/run/t1K8tNBor/mysqld.sock"'

Per environment options: remotes

As stated before you can have any number of remote configured and named as you need. Each of the remotes accepts the same set of configurations.

@note: production is not a keyword, just an arbitrary example string that you can customize.

production:
  vhost: 'https://example.com'
  wordpress_path: '/htdocs/html'
  # wordpress_absolute_path: '/var/www/wordpress/html'
  database:
    [...]

mandatory keys: vhost, wordpress_path, database

These work exactly as per the local environment. Read the previous section, but the following exceptions:

  1. If you use FTP as transfer protocol, the wordpress_path will be the relative path as you'll see inside your user's FTP jail. Usually it's something like /html or /htdocs. It's up to you to know how your hosting works ;)

  2. If you use FTP as transfer protocol, you should also specify the absolute FTP path as wordpress_absolute_path (you may need to recover this from the FILE magic constant

  3. Omit wordpress_absolute_path if you are on SSH

@note: you have always to configure the database credential based on how you configured wp-config.php; when working on a remote, Wordmove will firstly connect to it and within there it will connect to the database. So do not imagine to connect from your laptop to the database, but think from the WP install perspective. We think it's even easier to simply copy credential from the wp-config.php, isn't it?

exclude

production:
  exclude:
    - ".git/"
    - ".gitignore"
    - ".sass-cache/"
    - "node_modules/"
    - "bin/"
    - "tmp/*"
    - "Gemfile*"
    - "Movefile"
    - "movefile"
    - "movefile.yml"
    - "movefile.yaml"
    - "wp-config.php"
    - "wp-content/*.sql"

optional

The list of files listed under the exclude key will be ignored during push and pull operations. This let you do not push some files or folders or let you do not delete files which exist on the remote only. In the snippet above are listed the default options.

Note that these strings will be translated each into on --exclude xxx rsync's directive; this means that you could use there all the black magic you should've learned from the rsync's man page (see Work only on specific plugins or themes for an example).

paths

paths:
  wp_content: "wp-content-custom"
  wp_config: "wp-config-custom.php"
  uploads: "wp-content-custom/uploads"
  plugins: "wp-content-custom/plugins"
  mu_plugins: "wp-content-custom/plugins"
  themes: "wp-content-custom/themes"
  languages: "wp-content-custom/languages"

optional

With this option you can customize Wordpress internal paths if you put/name them in non standard ways. This must be configured in movefile.yml for both local and remote environments; for example, staging and production.

ssh/ftp

production:
  ssh:
  # ftp:

alternatives and mandatory

These two keys configure Wordmove with the desired protocol. We wish and recommend you use SSH over FTP. You can't have both the protocols present inside a single remote, but you can have multiple remotes with different protocols.

ssh
production:
  ssh:
    host: "host"
    user: "user"
    password: "password" # password is optional, will use public keys if available.
    port: 22 # Port is optional
    rsync_options: "--verbose" # Additional rsync options, optional
    gateway: # Gateway is optional
      host: "host"
      user: "user"
      password: "password" # password is optional, will use public keys if available.

mandatory key: host

  • user the user on the remote host
  • port is self-explanatory
  • password is a deprecated option which lets you hardcode your ssh password inside the movefile.yml. Read here for more informations.
  • rsync_options lets you pass any rsync valid option to the underlying rsync (you bet). This is just a proxy/command builder, so keep in mind that options are accepted based on the rsync version installed on your machine
  • gateway lets you use another ssh server as a proxy to your final destination. Also here password is depracated.

Please note that the only mandatory key is host, because you can configure SSH connections in ~/.ssh/config, thus using the specified host will call in all the options expressed there. For example, having a ~/.ssh/config with

Host client_X_staging
  Hostname 79.99.8.94
  User welaika
  Port 1337
  ProxyCommand ssh code -W %h:%p

you can fill movefile.yml just like this

staging:
  ssh:
    host: client_X_staging
ftp
production:
  ftp:
    user: "user"
    password: "password"
    host: "host"
    port: 21
    passive: true
    scheme: "ftps" # default "ftp"

mandatory keys: user, password, host

  • scheme: it defaults to ftp and could be ftps or sftp.
  • passive: can be true or false based on your hosting.
  • port: must be integer. If omitted will default to 21 or to 22 if scheme is configured to sftp
  • host: do not include protocol and/or port in the host, but use scheme and port configurations instead.

Please note that having password as mandatory key, makes this configuration security sensitive, thus risky to be put on a Git repository.

@note wordpress_absolute_path should be used together with wordpress_path when using FTP, based on your hosting configuration.

@note additional connection flags (es. 'set ssl:verify-certificate false' or debug switch) can be specified in lftp configuration files

@since 3.2.0 introduced sftp scheme and port configuration

hooks

production:
  hooks: # Remote hooks won't work with FTP
    push:
      before:
        - command: 'echo "do something"'
          where: local
          raise: false # raise is true by default
      after:
        - command: 'echo "do something"'
          where: remote
    pull:
      before:
        - command: 'echo "do something"'
          where: local
          raise: false
      after:
        - command: 'echo "do something"'
          where: remote

Entire hooks section in optional

@since 2.4 introduced

@since 5.0 the data structure has changed

hooks are separated in 2 groups: push and pull. Each group of commands will be evaluated while performing the matching action (wordmove push/wordmove pull).

Hooks will ignore what you will push or pull: they will be evaluated if you do wordmove push --all as much as you'd have done wordmove push --themes. I think making this more configurable would ends in an unusable mess of configurations.

Each group of hooks split itself in two subgroups: before and after. Commands brought by these groups will be executes at the matching timing: before pushing/pulling or after have pushed/pulled.

The deeper and last there is a sequence of object with 3 keys:

  • command: the actual command to run as a string (please single quote it to be safe)
  • where: accepts local or remote; indicates where the command will be run
  • raise: default to true; if set to false wordmove will continue its operations even if the command will fail (exit status > 0)

Remote hooks can't run over FTP; you will be warned if you'll try to do that.

It's redundant to say, but: hooks cannot be configured in the local environment.

Hooks must be configured in each remote environment you wish to use them.

You can read more about hooks on the dedicated wiki page.

forbid

production:
  forbid:
    push:
      db: false
      plugins: false
      themes: false
      languages: false
      uploads: false
      mu_plugins: false
    pull:
      db: false
      plugins: false
      themes: false
      languages: false
      uploads: false
      mu_plugins: false

Entire forbid section in optional

@since 3.0

forbid section needs to forbid (!) Wordmove's actions by config. By mean of actions we're speaking about push/pull plus a specific task. In the example above we have the complete list of tasks available to each action with default configurations (false value).

forbidden tasks will ignore command line flags. So if you have forbid.push.db: true in your movefile.yml and you'll call wordmove push -d you will have a warning such as:

Forbid warning message example

Note that tasks names are the same as in the long form of the command line flags.

Note that value must be BOOLEAN, not strings. wordmove doctor is able to detect such errors.

YAML tips

Moved in a dedicated wiki page

Add a custom footer
Add a custom sidebar
Clone this wiki locally