rsync --mkpath: Creating Missing Destination Dirs
rsync --mkpath creates the missing leading directories of the destination path so a deploy does not fail on a path that does not exist yet.
On a freshly provisioned server the target directory may not exist. Older rsync errors out; --mkpath (rsync 3.2.3+) creates the path for you.
What it does
--mkpath makes rsync create any missing leading directories of the destination before transferring, similar to mkdir -p for the target path. It was added in rsync 3.2.3, so older runner images do not have it; on those you must create the path with a separate ssh mkdir -p first.
Common usage
# Create /var/www/releases/<sha>/ if it does not exist, then sync
rsync -av --mkpath dist/ user@host:/var/www/releases/abc123/
# Pre-3.2.3 fallback: make the path over ssh first
ssh user@host 'mkdir -p /var/www/releases/abc123'
rsync -av dist/ user@host:/var/www/releases/abc123/Related options
| Flag | What it does |
|---|---|
| --mkpath | Create missing leading dirs of the destination |
| -R / --relative | Use the full source path to build dest dirs |
| -d / --dirs | Transfer directories without recursing |
| --no-implied-dirs | Do not create implied dirs from --relative |
In CI
Check rsync availability with "rsync --version" in your runner. If it is older than 3.2.3, use --mkpath nowhere and instead run ssh host mkdir -p <path> before the deploy. For release-directory deploys, creating the path is part of the standard flow.
Common errors in CI
Without the path existing, rsync prints "rsync: mkdir "/var/www/releases/abc123" failed: No such file or directory (2)" then "rsync error: error in file IO (code 11)". Add --mkpath (new rsync) or pre-create with ssh mkdir -p. On old rsync, "--mkpath: unknown option" means the binary predates 3.2.3.