Multiple environments explained

wordmove-ng assumes one of the environments will always be your development env. So:

Never rename the local section

local:
  vhost: "http://site.test"
  wordpress_path: "/Users/me/Sites/site-local"

  database:
    name: "wordpress"
    user: "root"
    password: "root"
    host: "127.0.0.1"

That is your local dev env and the local node is mandatory. Full stop.

Other nodes on the same level declare remotes. Here we have 2 remotes declared: test and live

local:
  vhost: "http://site.test"
  wordpress_path: "/Users/me/Sites/site-local"

  database:
    ...

test:
  vhost: "http://test.site.net"
  wordpress_path: "/dev/www/"

  database:
    ...

  exclude:
   ...

  ssh:
    ...

live:
  vhost: "http://site.net"
  wordpress_path: "/site/www/"

  database:
    ...

  exclude:
    ...

  ssh:
    ...

Note that they have the same indentation level as local.

When you pull/push you specify a remote with the -e flag if you have multiple remotes. With a single remote it is used by default and -e can be omitted.

When you pull, the destination is always local; tell wordmove-ng the environment from where it should take the bits with -e:

wordmove-ng pull -t -e live

syncs from live to local.

When you push, the destination is always the requested remote:

wordmove-ng push -t -e test

syncs from local to test.

Note about push/pull db

When you pull a DB, wordmove-ng dumps a copy of your local DB before overwriting it: wp-content/local-backup-TIMESTAMP.sql.gz.

When you push the DB to a remote, wordmove-ng saves a dump of the remote's DB the same way, named after the remote: wp-content/live-backup-TIMESTAMP.sql.gz, wp-content/test-backup-TIMESTAMP.sql.gz.

Avoid vhosts or paths where one environment's value is a prefix of another's (http://site.net and http://site.net.staging): the search-replace of the shorter one would rewrite the longer one too. doctor reports this.

Thanks to @charmcat who shared her troubleshooting with us and suggested writing this page 👍