wordmove

Wordmove's push and pull actions perform a mirror operation. This means:

1. New/updated files are transferred.
2. Files present on the destination that are NOT in the source will be deleted.

Critical Action: If you have files or directories on your remote server that must be preserved (e.g., specific logs, user-uploaded content not in your local dev environment, or system files), you MUST add them to the exclude list in your movefile.yml to prevent them from being deleted during a sync.

Wordmove supports multistage deployments (e.g., local, staging, production) by defining multiple environments in your movefile.yml.

Any top-level key in the YAML file (other than global, local, or database) is treated as a remote environment. To target a specific environment, use the -e flag with your command.

Example: Pushing to staging

wordmove push -e staging -d

Wordmove can automatically load environment variables from .env files. It looks for files matching the pattern .env{.#{environment},} in the start_dir.

For example, if your environment is set to production, Wordmove will look for .env.production or .env.

Wordmove uses a configuration file named Movefile (case-insensitive, e.g., movefile.yml, movefile.yaml, or Movefile) to define environments and connection settings.

When Wordmove searches for a Movefile, it looks in the current directory. If not found, it will traverse up the directory tree until it finds one or reaches a directory containing a wp-config.php file or the root directory.

The Movefile is parsed as YAML and supports ERB (Embedded Ruby) for dynamic configuration values.

Wordmove can use WP-CLI as a SQL adapter to perform search-replace operations. This adapter relies on the wp command being available in your system $PATH. It automatically handles the replacement of strings across all tables while skipping the guid column to prevent breaking WordPress post identity.

To ensure the adapter works correctly, it looks for the WordPress installation path in the following order of precedence:

1. A wp-cli.yml file located in your local path (containing a path key).
2. The current path provided by wp cli param-dump --with-values.
3. The local_path provided in your Wordmove configuration.

Wordmove provides a command-line interface for managing WordPress data transfers between environments. You can initialize a new configuration, check your environment setup, list available environments, and perform pull or push operations.

Core Commands

• init: Generates a new movefile.yml configuration file.
• doctor: Performs local configuration and environment checks to ensure everything is set up correctly.
• list: Lists all configured environments and virtual hosts.
• pull: Downloads WordPress data from a remote host to your local machine.
• push: Uploads WordPress data from your local machine to a remote host.
• --version or -v: Prints the current version of Wordmove.

Before starting, ensure you have the necessary peer dependencies installed and available in your system $PATH.

Mandatory Peer Dependencies:

• mysql: Required for database operations.
• mysqldump: Required for database operations.
• wp-cli: Required by default (though configurable).
• rsync: Required if using the SSH protocol.
• lftp: Required if using the FTP protocol.

Remote Server Requirements: Your remote server should have gzip, nice, mysql, and rsync installed.

To check your local configuration and environment readiness, run:

wordmove doctor

Wordmove is distributed as a Ruby gem. You can install it using the gem command.

To install the latest version:

gem install wordmove

To update an existing installation:

gem update wordmove

Wordmove supports SSH for secure file transfers and remote command execution.

Best Practice: Password-less Authentication It is highly recommended to use SSH public key authentication instead of writing passwords in your movefile.yml. To use your SSH public key, simply omit the password field from the database section of your remote environment configuration.

SSH Configuration Example:

production:
  ssh:
    host: host
    user: user
  database:
    host: host
    # password field omitted to use SSH keys

Wordmove supports FTP and SFTP protocols, though FTP support is considered legacy/discontinued. To use these, you must have lftp installed on your local machine.

FTP Configuration

• Use production.wordpress_path for the relative FTP path.
• Use production.wordpress_absolute_path for the absolute FTP path.
• To enable passive FTP, set production.ftp.passive: true.

SFTP Configuration

Since version 3.2.0, SFTP is fully supported. You can enable it by setting the production.ftp.scheme configuration key.

Note: Remote hooks do not work when using the FTP protocol.

To protect sensitive credentials and facilitate team sharing, you can use environment variables in your movefile.yml using ERB tags syntax: <%= ENV['VARIABLE_NAME'] %>.

Setting up variables

1. Using the shell:

export PROD_DB_USER="username"
export PROD_DB_PASS="password"

2. Using a .env file: Create a .env file in the same directory as your movefile.yml:

PROD_DB_USER="username"
PROD_DB_PASS="password"

Applying variables to movefile.yml

production:
  database:
    user: "<%= ENV['PROD_DB_USER'] %>"
    password: "<%= ENV['PROD_DB_PASS'] %>"