mvx
Move (rename) files and directories.
Mirrors GNU mv. Run it as mvx, or as gnux mvx.
Synopsis
mvx [OPTION]... SOURCE... DIRECTORYGNU reference
Description
mvx renames SOURCE to DEST, or moves several SOURCEs into DIRECTORY (also selectable with -t; -T forces the two-operand form). Within one filesystem a move is an atomic rename. Across filesystems mvx copies the source with all of its attributes, symbolic links and hard links intact and removes the original only after the copy has fully succeeded; --no-copy refuses such a move instead ('Invalid cross-device link'), so a move is always a rename. An existing destination is replaced unless -n (never), -u (only when the source is newer) or -i (ask first) says otherwise; a directory is never moved into itself, and a directory only replaces an empty directory. --backup[=CONTROL] (or -b) first renames each existing destination to a backup: CONTROL simple (or never) appends a suffix, numbered (t) appends .N with N one past the highest already there, existing (nil, the default) numbers the backup only when numbered backups already exist, and none (off) makes none; without a CONTROL the VERSION_CONTROL variable chooses. The suffix is ~, or SUFFIX with -S (which asks for backups by itself), or the SIMPLE_BACKUP_SUFFIX variable. A destination directory is backed up too, so with a backup a directory may replace a file and a file a directory; --backup cannot be combined with -n. GNU mv lets the last of -f, -i and -n win; mvx cannot see option order, so it prefers the most cautious instead: -n over -i over -f. On a terminal, gnux's terminal view colors the -v report: the verb (removed, created, renamed), each quoted name and the arrows, in the theme --theme or GNUX_THEME names; the words are GNU's, and piped or redirected output is never colored (--pretty=never or GNUX_PRETTY=never turns it off).
Permissions
Renaming needs write and search permission on both the source and destination directories, not on the file itself; in a sticky directory you must also own the entry. On a terminal, replacing a write-protected destination asks for confirmation unless -f is given. A cross-filesystem move additionally needs read permission on everything being moved, and preserves ownership only when privileged.
Use cases
- Renaming a file or directory in place.
- Sorting files into a directory, including with find/
xargsvia-t. - Relocating a tree to another disk without losing modes, times or links.
- Protecting existing files in scripts with
-n, or reviewing overwrites with-i. - Promoting a staged file over the live one only when it is newer (
-u). - Publishing a file atomically, never by a slow copy, with
--no-copy. - Atomically swapping a freshly written file into place after it is complete.
- Replacing a directory's name with
-Tinstead of moving into it. - Logging every move in a cleanup script with
-v.
Flags
--backup CONTROL[="$VERSION_CONTROL"] make a backup of each existing destination file; CONTROL is none (off), simple (never), existing (nil) or numbered (t)
-b, --backup-default like --backup but does not accept an argument
-f, --force do not prompt before overwriting
--help display this help and exit
-i, --interactive prompt before overwrite
-n, --no-clobber do not overwrite an existing file
--no-copy do not copy if renaming fails
-T, --no-target-directory treat DEST as a normal file
--pretty WHEN[="always"] the gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default
--strip-trailing-slashes remove any trailing slashes from each SOURCE argument
-S, --suffix SUFFIX override the usual backup suffix, '~', with SUFFIX
-t, --target-directory string move all SOURCE arguments into DIRECTORY
--theme NAME color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default
-u, --update string[="older"] control which existing files are updated: all, none, or older (the default for -u)
-v, --verbose explain what is being done
--version output version information and exitExamples
Rename a file
mvx draft.md final.mdMove several files into a directory, reporting each one
mvx -v a.log b.log archive/Move without ever overwriting an existing file
mvx -n photo.jpg ~/Pictures/Name the destination directory first (handy with xargs)
mvx -t build/out lib.a lib.soAsk before replacing an existing file
mvx -i new-config.yml config.ymlReplace a write-protected destination without being asked
mvx -f settings.tmp settings.jsonReplace the destination only when the source is newer
mvx -u staging/index.html public/index.htmlSkip files that already exist at the destination, using --update
mvx --update=none -v incoming/*.csv data/Rename a directory over an existing empty one instead of moving into it
mvx -T build-new buildMove a directory given with a trailing slash
mvx --strip-trailing-slashes logs/ old-logsWrite to a temporary file, then move it into place only on success
echox "generated" > report.tmp && mvx report.tmp report.txtMove every log file into an archive directory found with find
find . -maxdepth 1 -name '*.log' -print0 | xargs -0 mvx -t archive/Report an error when the move fails
mvx missing.txt dest/ || echox "move failed with status $?"Archive text files into a dated directory with the gnux shell
gnux shell -c 'mkdirx -p archive/2024 && mvx -v *.txt archive/2024/'Publish a finished build atomically, or fail if it is on another disk
mvx --no-copy build/site.new www/siteReplace a log with a new one, keeping the old one as server.log.old
mvx -S .old server.log.new server.logOptions
Each option has a page of its own, with its usage and examples.
- --backup: Make a backup of each existing destination file; CONTROL is none (off), simple (never), existing (nil) or numbered (t).
- -b, --backup-default: Like
--backupbut does not accept an argument. - -f, --force: Do not prompt before overwriting.
- -i, --interactive: Prompt before overwrite.
- -n, --no-clobber: Do not overwrite an existing file.
- --no-copy: Do not copy if renaming fails.
- -T, --no-target-directory: Treat DEST as a normal file.
- --pretty: The
gnuxterminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default. - --strip-trailing-slashes: Remove any trailing slashes from each SOURCE argument.
- -S, --suffix: Override the usual backup suffix, '~', with SUFFIX.
- -t, --target-directory: Move all SOURCE arguments into DIRECTORY.
- --theme: Color the view with the built-in theme NAME (
gnuxtheme picks and saves one); GNUX_THEME sets the default. - -u, --update: Control which existing files are updated: all, none, or older (the default for
-u). - -v, --verbose: Explain what is being done.
Exit status
| Status | Meaning |
|---|---|
| 0 | success: every operand was processed |
| 1 | failure: an operand could not be processed (diagnosed on standard error), or a command-line mistake |
Help in the terminal
mvx --help # options, first examples, exit status
gnux help mvx # this page: the full manual
gnux help mvx --OPTION # one option in depth, with its examples