Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
movefile.yml configurations explained
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
2 space indentation delines the data structure!
It's not optional nor coincidental!
Wordmove's configuration file naming is valid in different flavours:
Movefile(backward compatibility ref)
If this is clear, let's go.
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.
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: sql_adapter: "wpcli"
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
Funny is that
defaultadapter 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
You'll see the exact executed command in STDOUT
Per environment options: local
local: vhost: "http://localhost:8080"
vhost is the url you use to get to your site. If you work using
wp server - as I wish - the vhost will be the one in the above snippet. Keep in mind that if you install wordpress in subdirectories, the subdirectory should be part of the vhost. Possibly you should also configure accordingly the
define( 'WP_HOME', 'http://myproject.local' ); define( 'WP_SITEURL', 'http://myproject.local/wp' );
but it's up to you knowing how to configure your WP ;)
local: wordpress_path: "/home/me/dev/site"
Is simply the absolute path of you installation. With or without heading slash should work the same.
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
database.charsetoption is no more supported. Pass the '--default-charecter-set' flag into
database.mysql_optionsinstead, if you need to set the same option.
Here we point to our local database; I think it 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
You can pass as a string any
mysql accepted option inside the
mysqldump_options: "--max_allowed_packet=50MB --ignore-table=dbname.wp_cf7dbplugin_submits --ignore-table=dbname.wp_cf7dbplugin_st"
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.
production: vhost: 'https://example.com' wordpress_path: '/htdocs/html' # wordpress_absolute_path: '/var/www/wordpress/html'
mandatory keys: vhost, wordpress_path
These work exactly as per the
local environment. Read the previous section, but the following exceptions:
If you use FTP as transfer protocol, the
wordpress_pathwill be the relative path as you'll see inside your user's FTP jail. Usually it's something like
/htdocs. It's up to you to know how your hosting works ;)
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
wordpress_absolute_pathif 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,
Wordmovewill 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?
production: exclude: - ".git/" - ".gitignore" - ".sass-cache/" - "node_modules/" - "bin/" - "tmp/*" - "Gemfile*" - "Movefile" - "movefile" - "movefile.yml" - "movefile.yaml" - "wp-config.php" - "wp-content/*.sql"
The list of files listed under the
exclude key will be ignored during
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.
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"
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 external environments; for example, staging and production.
production: ssh: # ftp:
mutual 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.
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
userthe user on the remote host
passwordis a deprecated option which lets you hardcode your ssh password inside the
movefile.yml. Read here for more informations.
rsync_optionslets 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
gatewaylets you use another ssh server as a proxy to your final destination. Also here
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
Host client_X_staging Hostname 184.108.40.206 User welaika Port 1337 ProxyCommand ssh code -W %h:%p
you can fill
movefile.yml just like this
staging: ssh: host: client_X_staging
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
ftpand could be
passive: can be
falsebased on your hosting.
port: must be integer. If omitted will default to 21 or to 22 if
schemeis configured to
host: do not include protocol and/or port in the host, but use
Please note that having
password as mandatory key, makes this configuration security sensitive, thus risky to be put on a Git repository.
wordpress_absolute_pathshould be used together with wordpress_path when using FTP, based on your hosting configuration.
@since 3.2.0 introduced
production: hooks: # Remote hooks won't work with FTP push: before: local: - 'echo "Do something locally before push"' remote: - 'echo "Do something remotely before push"' after: local: - 'echo "Do something locally after push"' remote: - 'echo "Do something remotely after push"' pull: before: local: - 'echo "Do something locally before pull"' remote: - 'echo "Do something remotely before pull"' after: local: - 'echo "Do something locally after pull"' remote: - 'echo "Do something remotely after pull"'
hookssection in optional
hooks are separated in 2 groups:
pull. Each group of commands will be evaluated while performing the matching action (
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:
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 split is between
remote. This the environment where the commands will run.
remote environment will obviously be the one where the configuration is contained.
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
You can read more about hooks on the dedicated wiki page.
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
forbidsection in optional
forbid section needs to forbid (!) Wordmove's actions by config. By mean of actions we're speaking about
pull plus a specific task.
In the example above we have the complete list of tasks available to each action with default configurations (
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:
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.
Moved in a dedicated wiki page