Wordmove

https://github.com/welaika/wordmove
Admin
Wordmove is a command-line tool that automatically mirrors WordPress installations and database data...
Tokens:19,238
Snippets:235
Trust Score:9.3
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic Wordmove Installation (tl;dr)

Source: https://github.com/welaika/wordmove/wiki/Getting-Wordmove-installed-in-VVV-(or-any-Vagrant)

A concise set of commands to install Wordmove in a VVV environment when a quick setup is needed. This assumes a standard VVV setup and may not cover all edge cases.

```bash
$ apt-get install -y ruby-dev
$ gem install rubygems-update
$ update_rubygems
$ gem install wordmove
```

--------------------------------

### Install and Run Wordmove Locally

Source: https://github.com/welaika/wordmove/blob/master/CONTRIBUTING.md

Install the gem locally to use Wordmove from your development environment. Verify the installation by checking the version.

```fish
rake install
wordmove --version
```

--------------------------------

### Install Wordmove using RubyGems

Source: https://github.com/welaika/wordmove/wiki/[deprecated]-How-to-install-Wordmove-on-Windows-with-RubyInstaller

Install the Wordmove gem from the Command Prompt after setting up Ruby and the development kit.

```bash
gem install wordmove

```

--------------------------------

### Install lftp using Homebrew

Source: https://github.com/welaika/wordmove/wiki/Install-lftp-on-OSX-yosemite

Installs the lftp package using Homebrew. This is the primary command for installing lftp.

```shell
brew install lftp
```

--------------------------------

### Initialize Ruby Development Kit

Source: https://github.com/welaika/wordmove/wiki/[deprecated]-How-to-install-Wordmove-on-Windows-with-RubyInstaller

Run these commands in the Command Prompt after extracting the Ruby Development Kit to initialize and install it.

```bash
ruby dk.rb init

```

```bash
ruby dk.rb install

```

--------------------------------

### Install lftp from Homebrew Boneyard

Source: https://github.com/welaika/wordmove/wiki/Install-lftp-on-OSX-yosemite

Installs lftp from the Homebrew Boneyard if the standard formula is not found. This is a fallback option.

```shell
brew install homebrew/boneyard/lftp
```

--------------------------------

### Example movefile.yml Structure

Source: https://context7.com/welaika/wordmove/llms.txt

An annotated example of the `movefile.yml` structure, detailing global settings, local environment configuration, and remote production environment settings including database credentials, paths, exclusions, and SSH options.

```yaml
global:
  sql_adapter: wpcli   # Use "default" to fall back to the built-in adapter

local:
  vhost: http://mysite.local          # Must match `wp option get home`
  wordpress_path: /var/www/mysite     # Absolute path, no trailing slash

  database:
    name: mysite_db
    user: root
    password: "secret"
    host: localhost
    # port: 3306
    # mysqldump_options: '--max_allowed_packet=1G'
    # mysql_options: '--protocol=TCP'

production:
  vhost: https://example.com
  wordpress_path: /var/www/html

  database:
    name: prod_db
    user: prod_user
    password: "prod_secret"
    host: db.example.com

  exclude:
    - '.git/'
    - '.gitignore'
    - '.env'
    - 'node_modules/'
    - 'wp-config.php'
    - 'movefile.yml'
    - 'wp-content/*.sql.gz'

  ssh:
    host: example.com
    user: deploy
    # password: optional – omit to use SSH key auth
    # port: 22
    # rsync_options: '--verbose --itemize-changes'
    # gateway:         # optional SSH jump host
    #   host: jump.example.com
    #   user: jump_user
```

--------------------------------

### Install and Configure Wordmove in VVV

Source: https://github.com/welaika/wordmove/wiki/Getting-Wordmove-installed-in-VVV-(or-any-Vagrant)

Add this script to your `vvv-init.sh` file to automatically install and configure Wordmove during VVV provisioning. It checks for existing Ruby and Gem installations and installs Wordmove if not already present, also ensuring YAML can be required.

```bash
# Rubygems update

if [ $(gem -v|grep '^2.') ]; then
	echo "gem installed"
else
	apt-get install -y ruby-dev
	echo "ruby-dev installed"
	echo "gem not installed"
	gem install rubygems-update
	update_rubygems
fi

# wordmove install
wordmove_install="$(gem list wordmove -i)"
if [ "$wordmove_install" = true ]; then
  echo "wordmove installed"
else
  echo "wordmove not installed"
  gem install wordmove

  wordmove_path="$(gem which wordmove | sed -s 's/.rb/\/deployer\/base.rb/')"
  if [  "$(grep yaml $wordmove_path)" ]; then


    echo "can require yaml"
  else
    echo "can't require yaml"
    echo "set require yaml"

    sed -i "7i require\ \'yaml\'" $wordmove_path

    echo "can require yaml"

  fi
fi
```

--------------------------------

### Install Homebrew

Source: https://github.com/welaika/wordmove/wiki/Install-lftp-on-OSX-yosemite

Installs Homebrew, a package manager for macOS, which is required to install lftp.

```shell
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```

--------------------------------

### Install and Update Wordmove Gem

Source: https://context7.com/welaika/wordmove/llms.txt

Install, update, and verify the Wordmove gem installation. Ensure peer dependencies like rsync, mysql, mysqldump, wp-cli, and lftp are available on your system's PATH.

```bash
gem install wordmove
```

```bash
gem update wordmove
```

```bash
wordmove --version
```

```bash
# Peer dependencies required on the local machine:
# rsync      – required for SSH protocol file transfers
# mysql      – required for DB import
# mysqldump  – required for DB export
# wp-cli     – required by default (wpcli sql_adapter)
# lftp       – required for FTP protocol
```

--------------------------------

### Define WordPress Installation Path

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Specifies the absolute path to your local WordPress installation. Ensure no spaces are present or manually escape them.

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

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

--------------------------------

### Install Ruby and Wordmove via Bash

Source: https://github.com/welaika/wordmove/wiki/How-to-install-Wordmove-on-Windows-10-with-Bash

Installs Ruby and Wordmove using apt-get and gem commands in a Bash environment. Ensure you have the necessary repositories added.

```bash
sudo apt-get install rubygems-integration  
sudo apt-get install ruby-dev  
sudo apt-add-repository ppa:brightbox/ruby-ng  
sudo apt-get update  
sudo apt-get install ruby2.4  
sudo apt-get install build-essential  
sudo gem install wordmove  
```

--------------------------------

### Wordmove CLI Help - Main Commands

Source: https://github.com/welaika/wordmove/wiki/Usage-and-flags-explained

Displays a list of all available commands in the Wordmove CLI. Use this to get an overview of the tool's capabilities.

```bash
> wordmove help
Commands:
  wordmove --version, -v   # Print the version
  wordmove doctor          # Do some local configuration and environment checks
  wordmove help [TASK]     # Describe available tasks or one specific task
  wordmove init            # Generates a brand new Movefile
  wordmove list            # List all environments and vhosts
  wordmove pull            # Pulls WP data from remote host to the local machine
  wordmove push            # Pushes WP data from local machine to remote host
```

--------------------------------

### Wordmove Push/Pull - Example with Negation Flags

Source: https://github.com/welaika/wordmove/wiki/Usage-and-flags-explained

Demonstrates how to use the `--all` flag in conjunction with negation flags (e.g., `--no-db`) to perform a full site mirror excluding specific components like the database. This is useful for selective data transfers.

```bash
wordmove push --all --no-db -e production
```

```bash
wordmove push --all --no-db --no-wordpress -e production
```

--------------------------------

### MAMP mysqldump Usage Example

Source: https://github.com/welaika/wordmove/wiki/MAMP-tips

This output shows the expected usage information when the mysqldump command is found but not properly configured.

```bash
+Usage: mysqldump [OPTIONS] database [tables]
OR     mysqldump [OPTIONS] --databases [OPTIONS] DB1 [DB2 DB3...]
OR     mysqldump [OPTIONS] --all-databases [OPTIONS]
For more options, use mysqldump --help
```

--------------------------------

### Example MySQL Dump Command

Source: https://github.com/welaika/wordmove/wiki/Could-not-parse-PKey:-no-start-line-(ArgumentError)

This command is used to create a MySQL dump. Ensure you replace placeholders with your actual database credentials and desired output path.

```bash
mysqldump --host=<your db host> --user=<db user> --password=<your pass> <your db name> --result-file=/path/to/your/wordpress/wp-content/dump.sql
```

--------------------------------

### Global SQL Adapter Option

Source: https://context7.com/welaika/wordmove/llms.txt

Choose between 'wpcli' (default) and 'default' for database URL rewriting. 'wpcli' requires WP-CLI installed locally.

```yaml
global:
  sql_adapter: wpcli    # recommended; requires wp-cli in $PATH
  # sql_adapter: default  # built-in adapter, no wp-cli needed
```

```bash
# Confirm WP-CLI is available:
wp --info

# Wordmove internally executes something like:
# wp search-replace "https://example.com" "http://mysite.local" \
#   --path=/var/www/mysite --quiet --skip-columns=guid --all-tables --allow-root

# Skip URL adaptation entirely (e.g. same vhost on both ends):
wordmove pull -d -e production --no-adapt
```

--------------------------------

### Configure Remote Environment

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Example configuration for a remote environment, including virtual host, WordPress path, and database connection details. Mandatory keys are vhost, wordpress_path, and database.

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

--------------------------------

### Install wordmove with CFLAGS

Source: https://github.com/welaika/wordmove/wiki/No-CAS-operation-available-for-this-platform

Use this command when encountering platform-specific compilation errors during the 'wordmove' gem installation. It provides necessary C compiler flags.

```bash
gem install wordmove -- --with-cflags=-march=i686
```

--------------------------------

### Wordmove Installation with Publicly Writable Ruby Directory

Source: https://github.com/welaika/wordmove/wiki/Getting-Wordmove-installed-in-VVV-(or-any-Vagrant)

This method addresses potential permission issues when installing Wordmove in VVV, particularly with different Ruby versions. It makes the Ruby gems directory publicly writable before installing Wordmove.

```bash
sudo chmod -R 777 /usr/local/rvm/gems/ruby-2.4.1
gem install wordmove
```

```bash
sudo chmod -R 777 /usr/share/rvm/gems/ruby-2.4.0
```

--------------------------------

### Comprehensive Hook Examples for Push Operations

Source: https://github.com/welaika/wordmove/wiki/Hooks

Illustrates a variety of hooks for push operations, including frontend build processes, directory cleanup, notifications, WordPress specific commands, and file permission adjustments. Commands are specified with their execution location (`local` or `remote`).

```yaml
hooks:
  push:
    before:
      - command: 'npx webpack' # run webpack to build frontend
        where: local
      - command: 'rm -rf ./tmp/*' # blank local temp directory
        where: local
    after:
      - command: 'bash ./scripts/slack_notify.sh' # notify colleagues/customers on Slack/Ryver chat
        where: local
      - command: 'wp rewrite flush' # you know that :)
        where: remote
      - command: 'wp option set blog_public 0' # hide WP from search engine on staging
        where: remote
      - command: 'find . -type f -exec chmod 664 {}+' # fix permissions and blame your hosting provider
        where: remote
      - command: 'find . -type d -exec chmod 755 {}+' # N.B.: blaming is not yet supported by Wordmove
        where: remote
```

--------------------------------

### Execute Wordmove Directly

Source: https://github.com/welaika/wordmove/blob/master/CONTRIBUTING.md

Run the Wordmove executable directly from the bin directory for testing purposes. This bypasses the installed gem.

```fish
bin/wordmove --version
```

--------------------------------

### Configuring database credentials using environment variables

Source: https://github.com/welaika/wordmove/wiki/Environment-variables

Use environment variables to securely configure database credentials in your `movefile.yml`. This example shows how to set user and password.

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

--------------------------------

### Install Specific Net-SSH Version

Source: https://github.com/welaika/wordmove/wiki/Could-not-parse-PKey:-no-start-line-(ArgumentError)

If you encounter net-ssh version issues, install version 2.9.2 to resolve potential parsing errors.

```bash
gem install net-ssh --version=2.9.2
```

--------------------------------

### Advanced Wordmove Hook Examples

Source: https://github.com/welaika/wordmove/wiki/Hooks

Illustrates practical use cases for hooks, including frontend builds, cleanup, notifications, and WordPress specific commands. Commands must be quoted.

```yaml
hooks:
  push:
    before:
      local:
        - 'npx webpack' # run webpack to build frontend
        - 'rm -rf ./tmp/*' # blank local temp directory
    after:
      local:
        - 'bash ./scripts/slack_notify.sh' # notify colleagues/customers on Slack/Ryver chat
      remote:
        - 'wp rewrite flush' # you know that :)
        - 'wp option set blog_public 0' # hide WP from search engine on staging
        - 'find . -type f -exec chmod 664 {}+' # fix permissions and blame your hosting provider
        - 'find . -type d -exec chmod 755 {}+' # N.B.: blaming is not yet supported by Wordmove
```

--------------------------------

### Configure Local Environment vhost

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Specifies the virtual host URL for the local WordPress installation. This is a mandatory setting for the local environment.

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

--------------------------------

### Example of Error Handling in Hooks

Source: https://github.com/welaika/wordmove/wiki/Hooks

Demonstrates how to configure hooks to not raise exceptions when a command fails by setting `raise: false`. This allows subsequent commands to execute even if a prior one fails, ensuring the deploy process continues.

```yaml
hooks:
  push:
    before:
      - command: 'exit 1'
        where: remote
        raise: false
      - command: 'echo "Still working"'
        where: local
```

--------------------------------

### Scaffold movefile.yml with wordmove init

Source: https://context7.com/welaika/wordmove/llms.txt

Generate a new `movefile.yml` configuration file in the current directory. This command reads local WordPress database configuration from `wp-config.php` to create a default setup for SSH deployment.

```bash
cd /var/www/my-wordpress-site
wordmove init
# => Creates movefile.yml in the current directory
```

--------------------------------

### Advanced mysqldump Options

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Provides examples of advanced mysqldump options for managing database dumps, including packet size and ignoring specific tables.

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

--------------------------------

### Diagnose Environment with wordmove doctor

Source: https://context7.com/welaika/wordmove/llms.txt

Validates the `movefile.yml` schema and checks that all peer dependencies are installed and reachable. Run this before filing bug reports.

```bash
wordmove doctor
```

```bash
# Checks performed:
#   ✓ movefile.yml schema validation (via kwalify schemas)
#   ✓ mysql binary present and connectable
#   ✓ wp-cli present in $PATH
#   ✓ rsync present in $PATH
#   ✓ ssh connectivity
```

```bash
# If wp-cli is missing:
# ERROR -- : WP-CLI is not installed or not in your $PATH
# Fix: brew install wp-cli   (macOS)
#      curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
```

--------------------------------

### Using system variables for WordPress path

Source: https://github.com/welaika/wordmove/wiki/Environment-variables

Configure the WordPress path in your movefile using system variables like `ENV['HOME']`. The example shows how to dynamically set the path.

```yaml
local:
  vhost: "http://wordpress-site.localhost"
  wordpress_path: "<%= ENV['HOME'] %>/[wordpress directory path]/"
  # wordpress_path will be substituted with /home/user_name/[wordpress directory path]
```

--------------------------------

### Example Error Message in Wordmove

Source: https://github.com/welaika/wordmove/wiki/invalid-byte-sequence-in-UTF-8-while-pushing---pulling-db

This is a typical error traceback when Wordmove encounters an invalid byte sequence in a UTF-8 encoded file during database operations.

```ruby
    /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/sql_adapter.rb:44:in `gsub!': invalid byte sequence in US-ASCII (ArgumentError) 
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/sql_adapter.rb:44:in `serialized_replace!'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/sql_adapter.rb:36:in `replace_field!'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/sql_adapter.rb:25:in `replace_vhost!'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/sql_adapter.rb:17:in `adapt!'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/deployer/base.rb:168:in `adapt_sql'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/deployer/ssh.rb:39:in `pull_db'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/cli.rb:69:in `block in pull'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/cli.rb:37:in `block in handle_options'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/cli.rb:36:in `each'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/cli.rb:36:in `handle_options'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/lib/wordmove/cli.rb:68:in `pull'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/thor-0.19.1/lib/thor/command.rb:27:in `run'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/thor-0.19.1/lib/thor/invocation.rb:126:in `invoke_command'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/thor-0.19.1/lib/thor.rb:359:in `dispatch'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/thor-0.19.1/lib/thor/base.rb:440:in `start'
	from /usr/local/rvm/gems/ruby-2.3.0/gems/wordmove-2.0.0/exe/wordmove:6:in `<top (required)>'
	from /usr/local/rvm/gems/ruby-2.3.0/bin/wordmove:23:in `load'
	from /usr/local/rvm/gems/ruby-2.3.0/bin/wordmove:23:in `<main>'
	from /usr/local/rvm/gems/ruby-2.3.0/bin/ruby_executable_hooks:15:in `eval'
	from /usr/local/rvm/gems/ruby-2.3.0/bin/ruby_executable_hooks:15:in `<main>'
```

--------------------------------

### Fish Shell Environment Variable Export

Source: https://github.com/welaika/wordmove/wiki/YAML-tips

Example of exporting a global environment variable in Fish shell, which can be used by Wordmove's `movefile.yml` for dynamic path configuration.

```fish
set --export --global WORDPRESS_WORKS_PATH "$HOME/dev" # Wordmove automagic dev path
```

--------------------------------

### Initialize Wordmove Project

Source: https://github.com/welaika/wordmove/wiki/[deprecated]-How-to-install-Wordmove-on-Windows-with-RubyInstaller

Run this command in your main website folder to initialize a new Wordmove project and create the Movefile.

```bash
wordmove init

```

--------------------------------

### List Configured Environments with wordmove

Source: https://context7.com/welaika/wordmove/llms.txt

Prints all environments and their vhosts defined in the local `movefile.yml`. Useful for confirming the correct `-e` value to use.

```bash
wordmove list
```

```bash
# Example output:
# ✓ Using Movefile: /var/www/mysite/movefile.yml
# 
# Listing Local
# local: http://mysite.local
# 
# Listing Remotes
# staging: https://staging.example.com
# production: https://example.com
```

--------------------------------

### Perform FTP/SFTP Operations

Source: https://context7.com/welaika/wordmove/llms.txt

These commands demonstrate pushing themes/plugins or pulling the database using FTP/SFTP configurations.

```bash
wordmove push -t -p -e production    # push themes and plugins via FTP
wordmove pull -d -e production       # pull DB via PHP dump/import scripts
```

--------------------------------

### Run Homebrew Doctor

Source: https://github.com/welaika/wordmove/wiki/Install-lftp-on-OSX-yosemite

Executes the Homebrew doctor command to check for and fix potential issues with your Homebrew installation.

```shell
brew doctor
```

--------------------------------

### Uninstall Net-SSH Gem

Source: https://github.com/welaika/wordmove/wiki/Could-not-parse-PKey:-no-start-line-(ArgumentError)

Use this command to uninstall the net-ssh gem. You will be prompted to select the specific version to remove if multiple are installed.

```bash
gem uninstall net-ssh
```

--------------------------------

### Find mysqldump Executable

Source: https://github.com/welaika/wordmove/wiki/MAMP-tips

Use this command to locate the mysqldump executable within the MAMP installation directory if it's not in your system's PATH.

```bash
sudo find /Applications -type f -name mysqldump
```

--------------------------------

### Create lftp configuration directory

Source: https://github.com/welaika/wordmove/wiki/Install-lftp-on-OSX-yosemite

Creates the necessary directory for lftp configuration files in the user's home directory.

```shell
mkdir ~/.lftp
```

--------------------------------

### Wordmove CLI Help - Push Command Options

Source: https://github.com/welaika/wordmove/wiki/Usage-and-flags-explained

Details the available options and flags for the `push` command. These flags control which specific WordPress components are pushed from the local machine to the remote host.

```bash
> wordmove help push
Usage:
  wordmove push

Options:
  -w, [--wordpress], [--no-wordpress]
  -u, [--uploads], [--no-uploads]
  -t, [--themes], [--no-themes]
  -p, [--plugins], [--no-plugins]
  -m, [--mu-plugins], [--no-mu-plugins]
  -l, [--languages], [--no-languages]
  -d, [--db], [--no-db]
  -v, [--verbose], [--no-verbose]
  -s, [--simulate], [--no-simulate]
  -e, [--environment=ENVIRONMENT]
  -c, [--config=CONFIG]
      [--debug], [--no-debug]
      [--no-adapt], [--no-no-adapt]
      [--all], [--no-all]

Pushes WP data from local machine to remote host
```

--------------------------------

### Configure Local Database Connection

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Sets up connection details for your local database, including name, user, password, host, and port. mysqldump and mysql options can also be specified.

```yaml
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
```

--------------------------------

### Bash Shell Environment Variable Export

Source: https://github.com/welaika/wordmove/wiki/YAML-tips

Example of exporting a global environment variable in Bash shell, which can be used by Wordmove's `movefile.yml` for dynamic path configuration.

```bash
export WORDPRESS_WORKS_PATH="$HOME/dev"
```

--------------------------------

### Creating a .env file for environment variables

Source: https://github.com/welaika/wordmove/wiki/Environment-variables

Create a `.env` file in the same directory as your movefile to load environment variables. Wordmove automatically loads this file.

```dotenv
PROD_DB_USER="username"
PROD_DB_PASS="password"
```

--------------------------------

### Wordmove CLI - List Environments

Source: https://github.com/welaika/wordmove/wiki/Usage-and-flags-explained

Executes the `list` command to display all configured environments and their associated virtual hosts (vhosts) as defined in the `movefile.yml`.

```bash
> wordmove list
```

--------------------------------

### Multiple Remote Environments Configuration

Source: https://github.com/welaika/wordmove/wiki/Multiple-environments-explained

Configures multiple remote environments ('test' and 'live') alongside the mandatory 'local' environment. Each remote can specify vhost, WordPress path, database details, exclusions, and SSH settings.

```yaml
local:
  vhost: "http://site.dev"
  wordpress_path: "/Users/me/Sites/site-local"

  database:
    ...

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

  database:
    ...

  exclude:
   ...

  ssh:
    ...

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

  database:
    ...

  exclude:
    ...

  ssh:
    ...
```

--------------------------------

### Wordmove Configuration - Local Settings

Source: https://github.com/welaika/wordmove/wiki/How-to-install-Wordmove-on-Windows-10-with-Bash

Defines local WordPress path and MySQL host for Wordmove. Remember to replace 'C:\' with '/mnt/c/' and use '127.0.0.1' for the host.

```yaml
local:
  wordpress_path: "/mnt/c/PATH_TO_WORDPRESS/"
  host: "127.0.0.1"  
```

--------------------------------

### Configure Basic Hooks in movefile.yml

Source: https://github.com/welaika/wordmove/wiki/Hooks

Defines basic 'before' and 'after' hooks for push and pull operations, specifying command execution on local or remote environments. The `raise` option defaults to true and can be set to false to prevent script failure from halting the deploy.

```yaml
hooks:
  push:
    before:
      - command: 'echo "do something"'
        where: local
        raise: false
    after:
      - command: 'echo "do something"'
        where: remote
  pull:
    before:
      - command: 'echo "do something"'
        where: local
        raise: false
    after:
      - command: 'echo "do something"'
        where: remote
```

--------------------------------

### Run Wordmove Push Command

Source: https://github.com/welaika/wordmove/wiki/How-to-install-Wordmove-on-Windows-10-with-Bash

Executes the Wordmove push command to deploy all changes to the production environment. Ensure you are in the WordPress directory.

```bash
cd /mnt/c/PATH_TO_WORDPRESS/  
wordmove push -e production --all
```

--------------------------------

### Configure Global SQL Adapter

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Sets the SQL adapter for database operations. 'wpcli' uses WP-CLI's search-replace, while 'default' uses Wordmove's built-in adapter. This option is mandatory.

```yaml
global:
  sql_adapter: "wpcli"
```

--------------------------------

### Configure FTP Connection in movefile.yml

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Configure FTP connection parameters including user, password, host, port, passive mode, and scheme (ftp, ftps, sftp). User, password, and host are mandatory. The 'scheme' defaults to 'ftp' and 'port' defaults to 21 (or 22 for sftp).

```yaml
production:
  ftp:
    user: "user"
    password: "password"
    host: "host"
    port: 21
    passive: true
    scheme: "ftps" # default "ftp"
```

--------------------------------

### Configure FTP/SFTP Connection

Source: https://context7.com/welaika/wordmove/llms.txt

For servers without SSH, configure FTP, FTPS, or SFTP using the `ftp` block. This includes host, user, password, port, passive mode, and scheme. `wordpress_path` is relative, `wordpress_absolute_path` is server-side absolute.

```yaml
production:
  vhost: "https://example.com"
  wordpress_path: /html                         # relative FTP path
  wordpress_absolute_path: /var/www/html        # absolute server path

  database:
    name: prod_db
    user: prod_user
    password: "prod_pass"
    host: localhost

  ftp:
    host: ftp.example.com
    user: ftpuser
    password: "ftppass"
    port: 21
    passive: true
    scheme: ftps    # "ftp" (default) | "ftps" | "sftp"
```

--------------------------------

### Configure Multiple Environments in movefile.yml

Source: https://context7.com/welaika/wordmove/llms.txt

Define staging, test, and production targets in a single `movefile.yml`. Any top-level YAML key other than `global` and `local` defines a named remote environment.

```yaml
global:
  sql_adapter: wpcli

local:
  vhost: "http://mysite.local"
  wordpress_path: "/Users/me/Sites/mysite"
  database:
    name: mysite_local
    user: root
    password: "root"
    host: 127.0.0.1

staging:
  vhost: "https://staging.example.com"
  wordpress_path: "/var/www/staging"
  database:
    name: staging_db
    user: staging_user
    password: "staging_pass"
    host: localhost
  ssh:
    host: staging.example.com
    user: deploy

production:
  vhost: "https://example.com"
  wordpress_path: "/var/www/html"
  database:
    name: prod_db
    user: prod_user
    password: "prod_pass"
    host: localhost
  ssh:
    host: example.com
    user: deploy
```

```bash
# Target staging
wordmove push -d -e staging
```

```bash
# Target production
wordmove push --all -e production
```

```bash
# Pull DB from production to local
wordmove pull -d -e production
```

--------------------------------

### Wordmove CLI Help - Pull Command Options

Source: https://github.com/welaika/wordmove/wiki/Usage-and-flags-explained

Details the available options and flags for the `pull` command. These flags control which specific WordPress components are pulled from the remote host to the local machine.

```bash
> wordmove help pull
Usage:
  wordmove pull

Options:
  -w, [--wordpress], [--no-wordpress]
  -u, [--uploads], [--no-uploads]
  -t, [--themes], [--no-themes]
  -p, [--plugins], [--no-plugins]
  -m, [--mu-plugins], [--no-mu-plugins]
  -l, [--languages], [--no-languages]
  -d, [--db], [--no-db]
  -v, [--verbose], [--no-verbose]
  -s, [--simulate], [--no-simulate]
  -e, [--environment=ENVIRONMENT]
  -c, [--config=CONFIG]
      [--debug], [--no-debug]
      [--no-adapt], [--no-no-adapt]
      [--all], [--no-all]

Pulls WP data from remote host to the local machine
```

--------------------------------

### Local Development Environment Configuration

Source: https://github.com/welaika/wordmove/wiki/Multiple-environments-explained

Defines the mandatory local development environment. This section must be named 'local' and contains settings for vhost, WordPress path, and database credentials.

```yaml
local:
  vhost: "http://site.dev"
  wordpress_path: "/Users/me/Sites/site-local"

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

--------------------------------

### Configure SSH Connection in movefile.yml

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Set up SSH connection details for remote environments. The 'host' is mandatory, while 'user', 'password', 'port', 'rsync_options', and 'gateway' are optional. Password authentication is deprecated in favor of public key authentication.

```yaml
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.
```

--------------------------------

### Wordmove Push/Pull - Debugging with FTP

Source: https://github.com/welaika/wordmove/wiki/Usage-and-flags-explained

Explains the behavior of the `--debug` flag when used with `pull` or `push` commands over FTP. It prevents the deletion of the output file and prints its path for inspection, aiding in diagnosing issues with PHP libraries used for database import/export.

```bash
--debug
```

--------------------------------

### Chaining Commands in Hooks

Source: https://github.com/welaika/wordmove/wiki/Hooks

Shows how to chain multiple commands within a single hook entry by using shell operators like '&&'. This allows for sequential execution of related commands within the same hook context.

```bash
cd other_dire && pwd
```

--------------------------------

### Configure Wordmove Hooks in movefile.yml

Source: https://github.com/welaika/wordmove/wiki/Hooks

Define local and remote commands to be executed before and after push and pull operations. Ensure all commands are properly quoted.

```yaml
hooks:
  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"'
```

--------------------------------

### Pull Remote Data with wordmove

Source: https://context7.com/welaika/wordmove/llms.txt

Download selected WordPress components from a remote environment to your local machine. A local database backup is created before overwriting.

```bash
# Pull everything from production
wordmove pull --all -e production
```

```bash
# Pull only the database from staging
wordmove pull -d -e staging
```

```bash
# Pull themes and uploads
wordmove pull -t -u -e production
```

```bash
# Pull all but skip the database
wordmove pull --all --no-db -e production
```

```bash
# Dry-run to preview what would be downloaded
wordmove pull --all -e production --simulate
```

--------------------------------

### Push WordPress Components to Remote

Source: https://context7.com/welaika/wordmove/llms.txt

Transfer selected WordPress components from local to a remote environment using `wordmove push`. Files are synced with rsync, and the database is automatically dumped, compressed, uploaded, decompressed, imported, and URL-adapted. A backup of the remote DB is created before overwriting.

```bash
# Push everything (files + database) to production
wordmove push --all -e production

# Push only the database
wordmove push -d -e production

# Push themes and plugins only
wordmove push -t -p -e production

# Push everything EXCEPT the database
wordmove push --all --no-db -e production

# Push everything EXCEPT database and wp-core
wordmove push --all --no-db --no-wordpress -e production

# Simulate (dry-run) — shows what would be transferred without doing it
wordmove push --all -e production --simulate

# Push uploads using a custom movefile path
wordmove push -u -e production --config ./deploy/movefile.yml

# Full flag reference for push (and pull):
#   -w / --wordpress   WordPress core files (excludes wp-content)
#   -u / --uploads     wp-content/uploads
#   -t / --themes      wp-content/themes
#   -p / --plugins     wp-content/plugins
#   -m / --mu-plugins  wp-content/mu-plugins
#   -l / --languages   wp-content/languages
#   -d / --db          MySQL database
#   --all              All of the above
#   --no-{flag}        Exclude a specific component (used with --all)
```

--------------------------------

### Execute Push with SSH Configuration

Source: https://context7.com/welaika/wordmove/llms.txt

This command performs a push operation using the configured SSH settings.

```bash
wordmove push --all -e production
```

--------------------------------

### Configure SSH Connection using Local SSH Config

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Utilize an existing local SSH configuration file (e.g., ~/.ssh/config) by specifying the 'host' alias in movefile.yml. This allows Wordmove to use all connection details defined in the local config.

```yaml
staging:
  ssh:
    host: client_X_staging
```

--------------------------------

### Run RSpec and RuboCop Tests

Source: https://github.com/welaika/wordmove/blob/master/CONTRIBUTING.md

Execute the test suite and RuboCop linter using the 'rake' command. Ensure tests pass before submitting pull requests.

```fish
rake
```

--------------------------------

### Set Locale Environment Variables

Source: https://github.com/welaika/wordmove/wiki/invalid-byte-sequence-in-UTF-8-while-pushing---pulling-db

Setting LC_ALL and LANG to UTF-8 can resolve encoding issues by ensuring the system and applications use UTF-8. Remember to source the profile after changes.

```bash
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
```

```bash
source ~/.profile
```

--------------------------------

### Configuring Push and Pull Hooks in Wordmove

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Define custom commands to execute before or after 'push' and 'pull' operations. 'where' specifies 'local' or 'remote' execution, and 'raise: false' prevents operation failure if the command exits with a non-zero status.

```yaml
production:
  hooks:
    push:
      before:
        - command: 'echo "do something"'
          where: local
          raise: false
      after:
        - command: 'echo "do something"'
          where: remote
    pull:
      before:
        - command: 'echo "do something"'
          where: local
          raise: false
      after:
        - command: 'echo "do something"'
          where: remote
```

--------------------------------

### Push Changes with Wordmove

Source: https://github.com/welaika/wordmove/wiki/[deprecated]-How-to-install-Wordmove-on-Windows-with-RubyInstaller

Use this command to push your local changes to the development environment, including all modified files.

```bash
wordmove push -e development --all

```

--------------------------------

### Selective Plugin/Theme Sync with Rsync Exclude Patterns

Source: https://context7.com/welaika/wordmove/llms.txt

Use rsync include/exclude patterns to sync only specific plugins or themes. Prefixing with '+' creates an inclusion rule.

```yaml
production:
  exclude:
    - "+ wp-content/plugins/my-plugin/"   # include ONLY my-plugin
    - "wp-content/plugins/*"              # exclude all other plugins
    - "+ wp-content/themes/my-theme/"     # include ONLY my-theme
    - "wp-content/themes/*"              # exclude all other themes
  ssh:
    host: example.com
    user: deploy
```

```bash
# Push only the targeted plugin and theme
wordmove push -p -t -e production
```

--------------------------------

### Handle Spaces in mysqldump Socket Path

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Demonstrates how to correctly escape paths with spaces when specifying the MySQL socket for mysqldump.

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

--------------------------------

### Custom Rsync Options for CD Environments

Source: https://github.com/welaika/wordmove/wiki/Rsync-options-in-Continuous-Delivery-context

Use these rsync options in a CI/CD environment to ignore file times and permissions, and rely on checksums for accurate content comparison. This ensures transfers are based on content differences rather than metadata.

```yml
rsync_options: '--itemize-changes --chmod=D775,F664 --no-perms --no-times --checksum'
```

--------------------------------

### YAML Aliases for Configuration Reuse

Source: https://github.com/welaika/wordmove/wiki/YAML-tips

Use YAML anchors and aliases to define reusable configuration blocks, reducing duplication across different environments. This is particularly useful for common settings like database credentials or paths.

```yaml
global:
  sql_adapter: 'wpcli'

  default: &default # Default environment anchor for future reference
    vhost: "http://example.com"
    wordpress_path: "/var/www/your_site"
    paths: &paths # Paths anchor
      wp_content: "../app"
      plugins: "../app/plugins"
      mu_plugins: "../app/mu-plugins"
      uploads: "../app/uploads"
      languages: "../app/languages"
      themes: "../app/themes"
    database: &db # Database anchor
      host: localhost
      user: username
      password: password
      name: database
    ssh: &ssh # SSH anchor
      host: server
      user: foo

staging:
  <<: *default # Reference to the default environment hash, will be merged with sub keys
  vhost: http://staging.foo.com
  database:
    <<: *db # Reference the database hash
    name: db_staging
  ssh:
    <<: *ssh # Reference the ssh hash
    user: foobar

production:
  <<: *default
  vhost: http://www.foo.com
  database:
    <<: *db
    user: bar
    name: db_production
```

--------------------------------

### YAML with Local Variables and ERB Interpolations

Source: https://github.com/welaika/wordmove/wiki/YAML-tips

Shows how to declare and use local variables within a YAML `movefile.yml` using ERB syntax. This allows for DRYer configurations, especially when a variable is used in multiple places, such as paths and hook commands.

```yaml
global:
  sql_adapter: 'wpcli'

local:
  vhost: "http://localhost:8080"
  wordpress_path: "<%= ENV['WORDPRESS_WORKS_PATH'] %>/sshwordmove" # use an absolute path here

  database:
    [...]

production:
  <% prod_wp_path = "/home/sshwordmove/sshwordmove.welaika.com" %>
  vhost: "http://sshwordmove.welaika.com"
  wordpress_path: <%= prod_wp_path %> # use an absolute path here

  database:
    [...]

  exclude:
    [...]

  ssh:
    [...]

  hooks:
    pull:
      after:
        remote:
          - 'cd <%= prod_wp_path %> && wp core version'
```

--------------------------------

### Define Environments in movefile.yml

Source: https://github.com/welaika/wordmove/wiki/movefile.yml-configurations-explained

Defines the basic structure for environments in Wordmove's configuration file. 'global' and 'local' are mandatory, while others like 'production' or custom names can be added.

```yaml
global:
  ...
local:
  ...
production:
  ...
```

```yaml
global:
  ...
local:
  ...
mycoolremotehost:
  ...
```

```yaml
global:
  ...
local:
  ...
test:
  ...
production:
  ...
```

--------------------------------

### YAML with ERB for Dynamic Paths

Source: https://github.com/welaika/wordmove/wiki/YAML-tips

Demonstrates using ERB templating within a YAML `movefile.yml` to dynamically set the `wordpress_path` using an environment variable. This allows for environment-specific configurations.

```yaml
global:
  sql_adapter: "wpcli"

local:
  vhost: "http://localhost:8080"
  wordpress_path: "<%= ENV['WORDPRESS_WORKS_PATH'] %>/project_name"
```

--------------------------------

### Exporting environment variables in fish shell

Source: https://github.com/welaika/wordmove/wiki/Environment-variables

Set environment variables in the fish shell. These variables will be available to Wordmove.

```fish
# fish
set --export --global PROD_DB_USER "username"; set --export --global PROD_DB_PASS "password"
```

--------------------------------

### Wordmove Configuration - SSH Rsync Permissions

Source: https://github.com/welaika/wordmove/wiki/How-to-install-Wordmove-on-Windows-10-with-Bash

Configures rsync options for Wordmove to set correct file and folder permissions on the server. Use 755 for folders and 644 for files.

```yaml
ssh:
  rsync_options: "--chmod=Du=rwx,Dgo=rx,Fu=rw,Fgo=r"
```

--------------------------------

### Conditionally Run Hooks Based on Environment Variable Value

Source: https://github.com/welaika/wordmove/wiki/YAML-tips

Use `ENV.fetch('VAR', false) == 'value'` to check if an environment variable matches a specific string. This allows for different configurations based on the variable's content.

```yaml
hooks:
  pull:
    after:
      <% if ENV.fetch('BAR', false) == 'project_1' %>
      - where: remote
        command: 'find -type f -exec chmod 644 {} +'
        raise: true
      <% elsif ENV.fetch('BAR', false) == 'project_2' %>
      - where: remote
        command: 'php bin/my_script.php'
        raise: true
      <% end %>
```

--------------------------------

### Define Hooks for Deployment Lifecycle

Source: https://context7.com/welaika/wordmove/llms.txt

Hooks allow executing local or remote shell commands at specific points during push or pull operations. Specify the command, where it should run (local/remote), and if it's critical (raise). Remote hooks require SSH.

```yaml
production:
  vhost: "https://example.com"
  wordpress_path: "/var/www/html"
  ssh:
    host: example.com
    user: deploy
  hooks:
    push:
      before:
        - command: 'npm run build'          # build assets locally before pushing
          where: local
        - command: 'rm -rf ./tmp/*'         # clean temp files
          where: local
          raise: false                      # continue even if this fails
      after:
        - command: 'wp cache flush'         # flush object cache on remote
          where: remote
        - command: 'wp rewrite flush'       # flush rewrite rules
          where: remote
        - command: 'wp option set blog_public 0'  # hide from search engines on staging
          where: remote
        - command: 'bash ./scripts/notify_slack.sh'  # notify team
          where: local
    pull:
      before:
        - command: 'echo "Pulling from production…"'
          where: local
      after:
        - command: 'wp search-replace "https://example.com" "http://mysite.local" --all-tables'
          where: local
          raise: false
```

--------------------------------

### Execute Hooks During Push

Source: https://context7.com/welaika/wordmove/llms.txt

This command automatically triggers the defined push hooks (before and after) along with the file transfers.

```bash
# Hooks fire automatically during normal push/pull
wordmove push --all -e production
# => Runs push/before hooks, performs transfers, runs push/after hooks
```

--------------------------------

### Environment Variables and .env Support in movefile.yml

Source: https://context7.com/welaika/wordmove/llms.txt

Protect credentials by substituting them from environment variables or a `.env` file using ERB syntax. Wordmove processes `movefile.yml` through ERB before parsing.

```bash
# .env file (never commit to git)
PROD_SSH_HOST="example.com"
PROD_SSH_USER="deploy"
PROD_DB_NAME="prod_db"
PROD_DB_USER="prod_user"
PROD_DB_PASS="s3cr3t"
```

```yaml
# movefile.yml using ERB interpolation
global:
  sql_adapter: wpcli

local:
  vhost: "http://mysite.local"
  wordpress_path: "<%= ENV['HOME'] %>/Sites/mysite"
  database:
    name: mysite_local
    user: root
    password: ""
    host: localhost

production:
  vhost: "https://example.com"
  wordpress_path: "/var/www/html"
  database:
    name: "<%= ENV['PROD_DB_NAME'] %>"
    user: "<%= ENV['PROD_DB_USER'] %>"
    password: "<%= ENV['PROD_DB_PASS'] %>"
    host: localhost
  ssh:
    host: "<%= ENV['PROD_SSH_HOST'] %>"
    user: "<%= ENV['PROD_SSH_USER'] %>"
```
Tokens:
Raw