wordmove-ng 6.0.1 → 6.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f35d0da6f7b15e8f492351b76ea90e096fe73b5c94cf55d9e8f10a0e93eb3802
-  data.tar.gz: cebf5ecc1de41bf581c5b07cdf4446e87ead5b73c891393b60cfa7a6d702c14c
+  metadata.gz: 3b2ca340ce83622a7faa03d89c41573efb50933bd3c85f5427eac9f9ae07ee91
+  data.tar.gz: 9183010aadcc92084a70839d140bd62604c8e4058aac8411b809f70558e14d7d
 SHA512:
-  metadata.gz: dcb6cddeb0d95335204a1a40b2f429573ec114d0cffc7375e16af0eec4d2201df92c9c8f2040e809c610933853a1e71cf116ff3b3525a22f25d6b4da26366ac5
-  data.tar.gz: 35b2e3a3b29fb0e2ca9d6c128781cc0ca2feaa758b8efa49eeb71402c0ff2e683cb3bfcbbb8bf5d54d0d172ffd524a09579c7794b6da5a3da8638dc725c0bd8e
+  metadata.gz: 7411e375d8221a234dcb394ada25d0c3caa7e62225a328d5cd78d25f9d4a5be8887227844126d6045abd339b1c7c3b74966894d9fef5159c0e1fc1eab909a79e
+  data.tar.gz: a1914ff1d4a9ed0b533588bd1aca0b13157576e0e4d731c326edaf54db72916524d2402460350b3d0315d3ca623acf870d57c800b04a6c21955cd301cc333952

data/.github/workflows/release.yml

@@ -2,18 +2,21 @@
 #
 # 1. release-please watches master. From Conventional Commits it opens (and keeps
 #    updating) a "release PR" that bumps lib/wordmove/version.rb and CHANGELOG.md.
-#    Merging that PR creates the vX.Y.Z tag and the GitHub release.
-# 2. The publish job then builds the gem and pushes it to rubygems.org with
-#    trusted publishing (OIDC, no API key) and attaches the .gem to the release.
-#
-# The publish job also runs when a v* tag is pushed by hand, which is how the
-# very first release (v6.0.0) is cut.
+#    Merging that PR creates the vX.Y.Z tag and the GitHub release, using the
+#    RELEASE_PLEASE_TOKEN PAT so that the tag push triggers this workflow again.
+# 2. That tag push runs the publish job, which builds the gem, pushes it to
+#    rubygems.org with trusted publishing (OIDC, no API key) and attaches the
+#    .gem to the release. A v* tag pushed by hand at the head of master goes
+#    through the same job.
 #
 # One-time setup (see README "Releasing"):
 #   - rubygems.org: pending trusted publisher for gem wordmove-ng, repository
 #     tekgnosis-net/wordmove-ng, workflow release.yml, environment release
 #   - GitHub: environment "release"; Actions setting "Allow GitHub Actions to
-#     create and approve pull requests" enabled (needed by release-please)
+#     create and approve pull requests" enabled; repository secret
+#     RELEASE_PLEASE_TOKEN holding a fine-grained PAT scoped to this repository
+#     with Contents and Pull requests read/write (so release PRs run the checks
+#     that branch protection requires)
 
 name: Release
 
@@ -33,25 +36,23 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-    outputs:
-      release_created: ${{ steps.release.outputs.release_created }}
-      tag_name: ${{ steps.release.outputs.tag_name }}
     steps:
+      # A fine-grained PAT (secret RELEASE_PLEASE_TOKEN, contents + pull-requests
+      # read/write) instead of the built-in token: PRs opened with the built-in
+      # token never trigger the Tests workflow, which the branch protection on
+      # master requires before a release PR can be merged.
       - uses: googleapis/release-please-action@v4
         id: release
         with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 
   publish:
-    needs: [release-please]
-    # Runs after release-please created a release, or on a manually pushed tag.
-    # The `always()` is needed because release-please is skipped on tag pushes.
-    if: >-
-      always() && (
-        needs.release-please.outputs.release_created == 'true' ||
-        startsWith(github.ref, 'refs/tags/v')
-      )
+    # Only on tag pushes. release-please's tag (created with the PAT) triggers
+    # this workflow like any other push, so publishing from the master run as
+    # well would race it and fail with "Tag vX.Y.Z has already been created".
+    if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     environment: release
     permissions:
@@ -72,7 +73,7 @@ jobs:
 
       - name: Verify the tag points at the head of master
         env:
-          TAG: ${{ needs.release-please.outputs.tag_name || github.ref_name }}
+          TAG: ${{ github.ref_name }}
         run: |
           git fetch --tags --force
           tag_commit="$(git rev-parse "refs/tags/$TAG^{commit}")"
@@ -96,7 +97,7 @@ jobs:
       - name: Attach the gem to the GitHub release
         env:
           GH_TOKEN: ${{ github.token }}
-          TAG: ${{ needs.release-please.outputs.tag_name || github.ref_name }}
+          TAG: ${{ github.ref_name }}
         # release-please creates the release itself; a hand-pushed tag has none yet.
         run: |
           if ! gh release view "$TAG" >/dev/null 2>&1; then

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "6.0.1"
+  ".": "6.0.3"
 }

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to wordmove-ng are documented here. The project follows
 are listed at https://github.com/welaika/wordmove/releases; the kokiddp fork's changes
 between 5.2.2 and this project are summarised under 6.0.0.
 
+## [6.0.3](https://github.com/tekgnosis-net/wordmove-ng/compare/v6.0.2...v6.0.3) (2026-09-30)
+
+
+### Documentation
+
+* expand the Ruby installation guide ([#7](https://github.com/tekgnosis-net/wordmove-ng/issues/7)) ([5972e2c](https://github.com/tekgnosis-net/wordmove-ng/commit/5972e2cf45f8ef6ebf1c2724b7637a8f4d319e11))
+
+## [6.0.2](https://github.com/tekgnosis-net/wordmove-ng/compare/v6.0.1...v6.0.2) (2026-09-12)
+
+
+### Documentation
+
+* add cron automation guide and contrib/wordmove-sync.sh ([#4](https://github.com/tekgnosis-net/wordmove-ng/issues/4)) ([dbe3612](https://github.com/tekgnosis-net/wordmove-ng/commit/dbe36126976f9f5a0f0793208aed89bd5c7fc787))
+
 ## [6.0.1](https://github.com/tekgnosis-net/wordmove-ng/compare/v6.0.0...v6.0.1) (2026-09-09)
 
 

data/CLAUDE.md

@@ -103,7 +103,8 @@ Update the relevant page in the same commit as any user-facing behaviour change.
   `docs:`, `chore:`, `ci:`, `test:`, `refactor:`). release-please derives the version bump
   and CHANGELOG from them; never edit `lib/wordmove/version.rb` or `CHANGELOG.md` by hand.
   Releases are published to rubygems.org by `.github/workflows/release.yml` (trusted
-  publishing, no secrets).
+  publishing). `master` is protected for everyone including admins: branch, open a PR, let
+  the six `test` checks pass, merge. release-please needs the `RELEASE_PLEASE_TOKEN` secret.
 
 - Every shell fragment that includes user/config data goes through `Shellwords.escape`
   (or `Shellwords.split` for user-supplied option strings). Secrets must never appear in

data/README.md

@@ -35,7 +35,9 @@ in a few places where the old behaviour was unsafe. See [Upgrading from wordmove
 
 ## Installation
 
-Ruby 3.0 or newer is required.
+Ruby 3.0 or newer is required. If your system Ruby is older or missing, the docs walk
+through [installing Ruby](https://tekgnosis-net.github.io/wordmove-ng/installation/#ruby)
+with your package manager, rbenv, RVM, mise or Docker.
 
 ```bash
 gem install wordmove-ng
@@ -246,12 +248,17 @@ production:
 File sync mirrors the source: files missing on the source are deleted on the destination.
 Put anything you need to keep in `exclude`, which is always relative to `wordpress_path`.
 
+Scheduled syncs from cron or CI work out of the box; `contrib/wordmove-sync.sh` handles the
+environment cron lacks (Ruby version manager, `PATH`, no agent, no TTY, overlap lock, logs).
+See [Automation and cron](https://tekgnosis-net.github.io/wordmove-ng/automation/).
+
 The documentation site has the full reference:
 [Configuration](https://tekgnosis-net.github.io/wordmove-ng/configuration/),
 [Usage and flags](https://tekgnosis-net.github.io/wordmove-ng/usage/),
 [Database sync](https://tekgnosis-net.github.io/wordmove-ng/database-sync/),
 [Hooks](https://tekgnosis-net.github.io/wordmove-ng/hooks/),
 [Multiple environments](https://tekgnosis-net.github.io/wordmove-ng/environments/),
+[Automation and cron](https://tekgnosis-net.github.io/wordmove-ng/automation/),
 [Troubleshooting](https://tekgnosis-net.github.io/wordmove-ng/troubleshooting/).
 
 ## Logging
@@ -315,12 +322,12 @@ stored anywhere.
 1. Every push to `master` updates a "release PR" that bumps `lib/wordmove/version.rb` and
    `CHANGELOG.md` according to the commits since the last release.
 2. Merging that PR creates the `vX.Y.Z` tag and the GitHub release.
-3. The `publish` job in `.github/workflows/release.yml` then runs the test suite on the
-   tagged commit, builds the gem, pushes it to rubygems.org and attaches the `.gem` file to
-   the GitHub release.
+3. The tag push triggers the `publish` job in `.github/workflows/release.yml`, which runs
+   the test suite on the tagged commit, builds the gem, pushes it to rubygems.org and
+   attaches the `.gem` file to the GitHub release.
 
-Pushing a `v*` tag by hand at the head of `master` triggers the same publish job; that is
-how 6.0.0 was cut. Merge the release PR only when there is something worth shipping:
+Pushing a `v*` tag by hand at the head of `master` goes through the same publish job; that
+is how 6.0.0 was cut. Merge the release PR only when there is something worth shipping:
 release-please keeps proposing a patch release for any Conventional Commit, including
 `ci:` and `docs:` ones.
 
@@ -333,6 +340,11 @@ One-time setup for a new maintainer or a fork:
 - In the GitHub repository settings create an environment named `release`, and under
   *Actions → General* enable "Allow GitHub Actions to create and approve pull requests"
   so release-please can open its PR.
+- Create a fine-grained personal access token scoped to this repository with *Contents* and
+  *Pull requests* set to read and write, and store it as the repository secret
+  `RELEASE_PLEASE_TOKEN`. Pull requests opened with the built-in Actions token never trigger
+  other workflows, so without it the release PR cannot satisfy the required `test` checks on
+  the protected `master` branch.
 
 ## Credits and licence
 

data/contrib/wordmove-sync.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# Run a wordmove-ng sync from cron (or any non interactive context).
+#
+# Copy this file somewhere in your PATH, adjust the settings block or override
+# the variables from the environment, then add a crontab entry such as
+#
+#   MAILTO=you@example.com
+#   30 2 * * * /usr/local/bin/wordmove-sync.sh
+#
+# Cron provides almost no environment: no rvm/rbenv shims, no ssh-agent, no TTY.
+# This script makes ruby and the peer tools findable, relies on a key that
+# needs no passphrase (see the docs page "Automation"), refuses to overlap
+# with a still-running sync, and writes a plain-text log per run.
+#
+# Test it the way cron will run it before trusting the schedule:
+#   env -i HOME=$HOME SHELL=/bin/bash PATH=/usr/bin:/bin /usr/local/bin/wordmove-sync.sh
+set -euo pipefail
+
+# ---- settings (override with environment variables) --------------------------
+SITE_DIR="${SITE_DIR:-/path/to/wordpress}"        # directory holding movefile.yml
+ENVIRONMENT="${ENVIRONMENT:-production}"          # remote environment (-e)
+ACTION="${ACTION:-pull}"                          # pull or push
+COMPONENTS="${COMPONENTS:---all --no-db}"         # component flags
+LOG_DIR="${LOG_DIR:-$HOME/log/wordmove}"
+KEEP_LOGS="${KEEP_LOGS:-30}"                      # how many run logs to keep
+RUBY_VERSION="${RUBY_VERSION:-}"                  # e.g. ruby-3.4.9 for rvm; empty = whatever is on PATH
+# -----------------------------------------------------------------------------
+
+case "$ACTION" in
+  pull|push) ;;
+  *) echo "ACTION must be pull or push, got '$ACTION'" >&2; exit 2 ;;
+esac
+
+# Ruby version managers are not loaded by cron.
+if [ -n "$RUBY_VERSION" ] && [ -s "$HOME/.rvm/scripts/rvm" ]; then
+  # shellcheck disable=SC1091
+  source "$HOME/.rvm/scripts/rvm"
+  rvm use "$RUBY_VERSION" >/dev/null
+elif [ -d "$HOME/.rbenv/shims" ]; then
+  export PATH="$HOME/.rbenv/shims:$PATH"
+fi
+
+# Peer tools wordmove-ng shells out to (ssh, rsync, mysqldump, wp, ...).
+export PATH="$HOME/bin:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
+export LC_ALL="${LC_ALL:-C.UTF-8}"
+
+command -v wordmove-ng >/dev/null || { echo "wordmove-ng not found in PATH" >&2; exit 2; }
+
+mkdir -p "$LOG_DIR"
+LOG="$LOG_DIR/${ENVIRONMENT}-$(date +%Y%m%d-%H%M%S).log"
+LOCK_FILE="${LOCK_FILE:-${TMPDIR:-/tmp}/wordmove-${ENVIRONMENT}.lock}"
+
+cd "$SITE_DIR"
+
+# Refuse to start while a previous run is still active.
+exec 9>"$LOCK_FILE"
+if ! flock -n 9; then
+  echo "$(date '+%F %T') previous run still active, skipping" >>"$LOG"
+  exit 0
+fi
+
+# The output is coloured regardless of TTY; strip the escape codes for the log.
+# shellcheck disable=SC2086  # COMPONENTS is a list of flags on purpose
+{
+  echo "== $(date '+%F %T') wordmove-ng $ACTION -e $ENVIRONMENT $COMPONENTS"
+  wordmove-ng "$ACTION" -e "$ENVIRONMENT" $COMPONENTS
+  echo "== $(date '+%F %T') finished, exit 0"
+} 2>&1 | sed 's/\x1b\[[0-9;]*m//g' >>"$LOG"
+
+# Rotate logs: keep the newest KEEP_LOGS files for this environment.
+find "$LOG_DIR" -maxdepth 1 -name "${ENVIRONMENT}-*.log" -printf '%T@ %p\n' \
+  | sort -rn | tail -n +"$((KEEP_LOGS + 1))" | cut -d' ' -f2- | xargs -r rm -f

data/docs/automation.md

@@ -0,0 +1,166 @@
+---
+title: Automation and cron
+nav_order: 10
+---
+
+# Automation and cron
+{: .no_toc }
+
+wordmove-ng never prompts, so it runs unattended: from cron, systemd timers, CI runners or deploy scripts. What differs from an interactive shell is the environment, and this page covers exactly that.
+
+1. TOC
+{:toc}
+
+## What cron does not give you
+
+- **No version manager.** rvm and rbenv shims are loaded by your shell profile, which cron does not read. `ruby`, `gem` executables and the gemset must be made visible explicitly.
+- **No ssh-agent.** There is no agent socket, so the SSH key must be usable without one: a key without a passphrase, or a key held by a system agent you start yourself.
+- **A minimal `PATH`.** `rsync`, `mysqldump`, `wp` and friends installed under `~/bin`, `/usr/local/bin` or a MAMP/Local directory are not found unless you add them.
+- **No TTY.** Output is still coloured; strip the escape codes when logging to a file.
+
+`wordmove-ng` itself is already safe here: SSH runs with `BatchMode=yes`, a failing key authentication is an error rather than a hanging prompt, prerequisites are checked before any side effect, and every failure exits non-zero.
+
+## Prepare once
+
+### A key cron can use
+{: .no_toc }
+
+Create a dedicated key without a passphrase and restrict what it can do on the server:
+
+```bash
+ssh-keygen -t ed25519 -N '' -f ~/.ssh/wordmove_cron_ed25519 -C wordmove-cron
+```
+
+In the remote `~/.ssh/authorized_keys`, prefix the public key with restrictions:
+
+```
+from="203.0.113.10",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-ed25519 AAAA… wordmove-cron
+```
+
+Then point the movefile at a `~/.ssh/config` entry that names the key, so the movefile stays free of machine-specific paths:
+
+```
+Host prod-wordmove
+  Hostname example.com
+  User deploy
+  IdentityFile ~/.ssh/wordmove_cron_ed25519
+  IdentitiesOnly yes
+```
+
+```yaml
+production:
+  ssh:
+    host: prod-wordmove
+```
+
+### Secrets in `.env`
+{: .no_toc }
+
+Keep database passwords in a `.env` file next to `movefile.yml` with mode `600`, referenced as `<%= ENV['PROD_DB_PASS'] %>`. Never put them in the crontab, which is readable by other means and shows up in logs.
+
+### Guard rails in the movefile
+{: .no_toc }
+
+A scheduled job should not be able to do more than it was written for, even if the script is edited later. Use `forbid`:
+
+```yaml
+production:
+  forbid:
+    push:
+      db: true          # a file-sync job must never push the database
+      uploads: true
+```
+
+and `exclude` for anything that lives on one side only, because syncs **mirror** the source: a scheduled `pull --all` overwrites local changes, a scheduled `push --all` overwrites uploads added through the WordPress admin since the last run.
+
+## The script
+
+The repository ships [`contrib/wordmove-sync.sh`](https://github.com/tekgnosis-net/wordmove-ng/blob/master/contrib/wordmove-sync.sh). Copy it to `/usr/local/bin/`, adjust the settings block at the top or override the variables from the environment. It
+
+- loads rvm (`RUBY_VERSION=ruby-3.4.9`) or rbenv, and extends `PATH` for the peer tools;
+- refuses to start while a previous run holds the lock, so overlapping runs cannot happen;
+- writes one plain-text log per run to `~/log/wordmove/` with colour codes stripped, and keeps the last 30;
+- exits non-zero when the sync fails, so cron mails you when `MAILTO` is set.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SITE_DIR="${SITE_DIR:-/path/to/wordpress}"        # directory holding movefile.yml
+ENVIRONMENT="${ENVIRONMENT:-production}"
+ACTION="${ACTION:-pull}"                          # pull or push
+COMPONENTS="${COMPONENTS:---all --no-db}"
+LOG_DIR="${LOG_DIR:-$HOME/log/wordmove}"
+RUBY_VERSION="${RUBY_VERSION:-}"                  # e.g. ruby-3.4.9 for rvm
+
+if [ -n "$RUBY_VERSION" ] && [ -s "$HOME/.rvm/scripts/rvm" ]; then
+  source "$HOME/.rvm/scripts/rvm"; rvm use "$RUBY_VERSION" >/dev/null
+elif [ -d "$HOME/.rbenv/shims" ]; then
+  export PATH="$HOME/.rbenv/shims:$PATH"
+fi
+export PATH="$HOME/bin:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
+
+mkdir -p "$LOG_DIR"
+LOG="$LOG_DIR/${ENVIRONMENT}-$(date +%Y%m%d-%H%M%S).log"
+cd "$SITE_DIR"
+
+exec 9>"/tmp/wordmove-${ENVIRONMENT}.lock"
+flock -n 9 || { echo "$(date '+%F %T') previous run still active" >>"$LOG"; exit 0; }
+
+{
+  echo "== $(date '+%F %T') wordmove-ng $ACTION -e $ENVIRONMENT $COMPONENTS"
+  wordmove-ng "$ACTION" -e "$ENVIRONMENT" $COMPONENTS
+  echo "== $(date '+%F %T') finished"
+} 2>&1 | sed 's/\x1b\[[0-9;]*m//g' >>"$LOG"
+```
+
+(abridged; the shipped file adds validation and log rotation)
+
+## Crontab
+
+Nightly at 02:30 local time, with failures mailed to you:
+
+```
+MAILTO=you@example.com
+30 2 * * * SITE_DIR=/home/me/sites/example RUBY_VERSION=ruby-3.4.9 /usr/local/bin/wordmove-sync.sh
+```
+
+Several sites or environments are just several lines with different variables. Stagger them so their windows do not overlap on the same remote.
+
+## Test it the way cron runs it
+
+A missing `PATH` entry or an unreadable key only shows up under cron's empty environment, so reproduce that before trusting the schedule:
+
+```bash
+env -i HOME=$HOME SHELL=/bin/bash PATH=/usr/bin:/bin \
+  SITE_DIR=/home/me/sites/example RUBY_VERSION=ruby-3.4.9 /usr/local/bin/wordmove-sync.sh
+echo "exit $?"
+tail -n 40 ~/log/wordmove/production-*.log
+```
+
+Running `wordmove-ng doctor` under the same `env -i` prefix is the quickest check that the key and every tool resolve without an agent.
+
+## Database jobs
+
+For a scheduled database push enable `global.maintenance_mode` so the seconds between import and `wp search-replace` show visitors the maintenance page instead of the wrong URLs. Scheduled database pulls are the common case (a nightly copy of production for development) and need nothing special; each run leaves a `local-backup-<timestamp>.sql.gz` in `wp-content/`, so prune those occasionally.
+
+## systemd timer instead of cron
+
+The same script works as a `oneshot` service:
+
+```ini
+# ~/.config/systemd/user/wordmove-sync.service
+[Service]
+Type=oneshot
+Environment=SITE_DIR=/home/me/sites/example RUBY_VERSION=ruby-3.4.9
+ExecStart=/usr/local/bin/wordmove-sync.sh
+
+# ~/.config/systemd/user/wordmove-sync.timer
+[Timer]
+OnCalendar=*-*-* 02:30:00
+Persistent=true
+[Install]
+WantedBy=timers.target
+```
+
+`systemctl --user enable --now wordmove-sync.timer`, and `journalctl --user -u wordmove-sync` for the output. Enable lingering (`loginctl enable-linger $USER`) so user timers run without a login session.

data/docs/contributing.md

@@ -1,6 +1,6 @@
 ---
 title: Contributing and releasing
-nav_order: 11
+nav_order: 12
 ---
 
 # Contributing and releasing
@@ -38,9 +38,11 @@ Releases are automated by [release-please](https://github.com/googleapis/release
 
 1. Every push to `master` updates a "release PR" that bumps the version and the changelog from the commits since the last release. release-please proposes a patch release for any Conventional Commit, `ci:` and `docs:` included, so merge the PR only when there is something worth shipping.
 2. Merging it creates the `vX.Y.Z` tag and the GitHub release.
-3. The `publish` job in `.github/workflows/release.yml` re-runs the suite on the tagged commit, builds the gem, pushes it to rubygems.org and attaches the `.gem` file to the GitHub release.
+3. The tag push triggers the `publish` job in `.github/workflows/release.yml`, which re-runs the suite on the tagged commit, builds the gem, pushes it to rubygems.org and attaches the `.gem` file to the GitHub release.
 
-Pushing a `v*` tag by hand at the head of `master` triggers the same publish job.
+Pushing a `v*` tag by hand at the head of `master` goes through the same publish job.
+
+`master` is protected: changes land through pull requests whose `test` checks pass, and the rules apply to administrators too. release-please opens its PR with a fine-grained personal access token (secret `RELEASE_PLEASE_TOKEN`) because PRs opened with the built-in Actions token never trigger the checks.
 
 ## This documentation
 

data/docs/index.md

@@ -51,6 +51,7 @@ It is the maintained, independent successor of [Wordmove](https://github.com/wel
 | know what each flag does | [Usage and flags]({{ site.baseurl }}/usage/) |
 | know exactly what happens to my database | [Database sync]({{ site.baseurl }}/database-sync/) |
 | run commands before or after a deploy | [Hooks]({{ site.baseurl }}/hooks/) |
+| schedule syncs from cron or CI | [Automation and cron]({{ site.baseurl }}/automation/) |
 | fix a problem | [Troubleshooting]({{ site.baseurl }}/troubleshooting/) |
 
 ## Credits

data/docs/installation.md

@@ -11,11 +11,124 @@ nav_order: 2
 
 ## Ruby
 
-wordmove-ng needs **Ruby 3.0 or newer**. Check with `ruby --version`. If your system Ruby is older or missing, use a version manager:
+wordmove-ng needs **Ruby 3.0 or newer** and is tested on 3.0 through 4.0. Check what you have:
 
-- [rbenv](https://github.com/rbenv/rbenv#installation)
-- [RVM](https://rvm.io/)
-- [mise](https://mise.jdx.dev/) (`mise use -g ruby@3.4`)
+```bash
+ruby --version
+```
+
+If that prints 3.0 or newer you can skip to [the gem](#the-gem). Otherwise pick one of the routes below. A version manager is the usual choice: it leaves the system Ruby alone (several distributions depend on it), installs gems into your home directory without `sudo`, and lets you upgrade Ruby later without touching anything else. Any current 3.x works; `3.4` is a good default and is what the project itself uses.
+
+### Option A: your distribution's Ruby
+{: .no_toc }
+
+The quickest route when the packaged version is recent enough. Debian 12, Ubuntu 22.04 and later, Fedora and Arch all ship Ruby 3.x.
+
+```bash
+# Debian / Ubuntu
+sudo apt update && sudo apt install -y ruby-full build-essential
+# Fedora
+sudo dnf install -y ruby ruby-devel @development-tools
+# Arch
+sudo pacman -S ruby base-devel
+```
+
+Then install the gem for your user only, so no `sudo` is needed and the system stays untouched:
+
+```bash
+gem install --user-install wordmove-ng
+```
+
+`--user-install` puts executables under `~/.local/share/gem/ruby/<version>/bin` (older Rubies: `~/.gem/ruby/<version>/bin`). Add that directory to your `PATH` in `~/.bashrc` or `~/.zshrc`; `gem env` prints the exact path under `USER INSTALLATION DIRECTORY`.
+
+### Option B: rbenv
+{: .no_toc }
+
+Lightweight, shell-agnostic, and packaged everywhere. `rbenv` selects a Ruby; the `ruby-build` plugin compiles one.
+
+```bash
+# macOS
+brew install rbenv ruby-build
+# Debian / Ubuntu (rbenv from apt is often old; the git checkout below is current)
+sudo apt install -y git build-essential autoconf libssl-dev libyaml-dev zlib1g-dev libffi-dev libgmp-dev rustc
+git clone https://github.com/rbenv/rbenv.git ~/.rbenv
+git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
+~/.rbenv/bin/rbenv init      # prints the line to add to your shell profile; add it, then reopen the terminal
+```
+
+```bash
+rbenv install 3.4.11         # compiles Ruby, takes a few minutes
+rbenv global 3.4.11
+ruby --version
+gem install wordmove-ng
+rbenv rehash                 # makes the wordmove-ng executable visible
+```
+
+`rbenv install --list` shows the versions available; run `git -C ~/.rbenv/plugins/ruby-build pull` (or `brew upgrade ruby-build`) if a recent one is missing.
+
+### Option C: RVM
+{: .no_toc }
+
+Heavier than rbenv but familiar to many WordPress developers, and its gemsets isolate one project's gems from another's.
+
+```bash
+gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+\curl -sSL https://get.rvm.io | bash -s stable
+source ~/.rvm/scripts/rvm    # or reopen the terminal
+```
+
+```bash
+rvm install 3.4.11
+rvm use 3.4.11 --default
+gem install wordmove-ng
+```
+
+RVM installs the build dependencies for you (it may ask for your `sudo` password once). To keep wordmove-ng in its own gemset: `rvm gemset create wordmove && rvm use 3.4.11@wordmove --default` before `gem install`. If you use the [cron script]({{ site.baseurl }}/automation/), set `RUBY_VERSION` to the same `ruby-3.4.11` or `ruby-3.4.11@wordmove` string.
+
+### Option D: mise
+{: .no_toc }
+
+One tool for Ruby, Node, PHP and more, with a single config file per project. Good if you already manage other runtimes with it.
+
+```bash
+curl https://mise.run | sh
+echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc   # or: mise activate zsh >> ~/.zshrc
+exec $SHELL
+```
+
+```bash
+mise use --global ruby@3.4
+ruby --version
+gem install wordmove-ng
+```
+
+mise compiles Ruby through ruby-build as well, so on Linux install the same build packages listed under rbenv first; on macOS `brew install openssl@3 readline libyaml gmp autoconf`.
+
+### Docker
+{: .no_toc }
+
+If you would rather not install Ruby at all, run wordmove-ng from the official Ruby image. Mount your site and your SSH configuration, and make sure the peer tools are installed in the container:
+
+```bash
+docker run --rm -it \
+  -v "$PWD":/site -w /site \
+  -v "$HOME/.ssh":/root/.ssh:ro \
+  ruby:3.4 bash -c 'apt-get update -qq && apt-get install -y -qq rsync openssh-client mariadb-client >/dev/null \
+    && gem install -q wordmove-ng && wordmove-ng doctor'
+```
+
+For repeated use bake that into a small Dockerfile. Note that `local` in your movefile then means "inside the container": `wordpress_path` is `/site`, and the local database must be reachable from the container (`host: host.docker.internal` on Docker Desktop, or the compose service name).
+
+### Checking the result
+{: .no_toc }
+
+```bash
+ruby --version        # 3.0 or newer
+gem --version
+wordmove-ng --version
+```
+
+If `wordmove-ng` is not found right after installing, the executable directory is not in your `PATH` yet: open a new terminal, and for rbenv run `rbenv rehash`. `gem env` shows where executables were placed.
 
 ## The gem
 

data/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 ---
 title: Troubleshooting
-nav_order: 10
+nav_order: 11
 ---
 
 # Troubleshooting and FAQ

data/docs/usage.md

@@ -109,6 +109,10 @@ exclude:
 
 The same works for themes and any other folder.
 
+## Running unattended
+
+wordmove-ng never prompts, so it can run from cron, systemd timers or CI. The environment those give you is the only difference; see [Automation and cron]({{ site.baseurl }}/automation/) for a ready-made script and the SSH key setup.
+
 ## Rsync options in a continuous delivery context
 
 The default rsync flags are `-rlpt`. On a CI runner every file is freshly checked out, so `--times` triggers a full transfer every time and `--perms` may not be what you want:

data/lib/wordmove/version.rb

@@ -1,3 +1,3 @@
 module Wordmove
-  VERSION = "6.0.1".freeze
+  VERSION = "6.0.3".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wordmove-ng
 version: !ruby/object:Gem::Version
-  version: 6.0.1
+  version: 6.0.3
 platform: ruby
 authors:
 - Kumar
@@ -251,11 +251,13 @@ files:
 - bin/setup
 - bin/thor
 - bin/wordmove-ng
+- contrib/wordmove-sync.sh
 - deploy/deploy.sh
 - docs/Gemfile
 - docs/README.md
 - docs/_config.yml
 - docs/assets/images/wordmove-ng.png
+- docs/automation.md
 - docs/configuration.md
 - docs/contributing.md
 - docs/database-sync.md