cpx
Copy files and directories.
Mirrors GNU cp. Run it as cpx, or as gnux cpx.
Synopsis
cpx [OPTION]... SOURCE... DIRECTORYGNU reference
Description
cpx copies SOURCE to DEST, or several SOURCEs into DIRECTORY (also selectable with -t; -T forces the two-operand form). Directories are copied only with -r, and a directory is never copied into itself. A new file receives the source's permission bits filtered by the umask; -p or --preserve[=LIST] carries over mode, ownership, timestamps and hard links, and -a is shorthand for -dR --preserve=all. Symbolic links are followed unless copying recursively; -P/-d keep them as links, -L follows them everywhere and -H only on the command line. -l and -s create hard or symbolic links instead of copying data. Existing destinations are overwritten unless -n (never), -u (only when the source is newer) or -i (ask first) says otherwise; -f removes a destination that cannot be opened and tries again, and --remove-destination removes every existing destination before writing it, so a destination symbolic link is replaced rather than written through and a file that other names share is not changed under them. --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 merged into, never backed up; a file whose backup is the source is refused ('backing up ... might destroy source'); -f -b FILE FILE copies FILE to its backup name, as in GNU; and --backup cannot be combined with -n. GNU cp lets the last of conflicting options win; cpx cannot see option order, so it prefers the most cautious instead: -n overrides -i, and an explicit -P/-d overrides -H, which overrides -L. 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
Copying needs read permission on each source and write and search permission on the destination directory. Without -p the copy is owned by the invoking user and its mode is the source's mode minus the umask. Preserving ownership requires privilege; an ordinary user silently keeps their own ownership, as with GNU cp. On Windows only the read-only attribute and modification time are carried over.
Use cases
- Duplicating a file before editing it, so the original can be restored.
- Copying a directory tree with
-r, or a faithful archive of it with-a. - Refreshing a mirror with
-uso only newer files are rewritten. - Filling in missing defaults without touching customized files (
--update=none). - Guarding existing files in scripts with
-n, or interactively with-i. - Building a tree of hard links (
-al) or symlinks (-s) instead of duplicating data. - Recreating selected files under a backup directory with their paths intact (
--parents). - Replacing a read-only destination in a deployment step with
-f. - Deploying over a file a running program has open, or one hard-linked elsewhere, with
--remove-destination. - Collecting build artifacts into a directory named up front with
-t.
Flags
-a, --archive same as -dR --preserve=all
--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
-L, --dereference always follow symbolic links in SOURCE
-H, --dereference-args follow command-line symbolic links in SOURCE
-f, --force if an existing destination file cannot be opened, remove it and try again
--help display this help and exit
-i, --interactive prompt before overwrite
-l, --link hard link files instead of copying
-n, --no-clobber do not overwrite an existing file
-P, --no-dereference never follow symbolic links in SOURCE
-d, --no-dereference-links same as --no-dereference --preserve=links
--no-preserve string don't preserve the listed attributes
-T, --no-target-directory treat DEST as a normal file
-x, --one-file-system stay on this file system
--parents use the full source file name under DIRECTORY
--preserve string[="mode,ownership,timestamps"] preserve the listed attributes: mode, ownership, timestamps, links, all
-p, --preserve-default same as --preserve=mode,ownership,timestamps
--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
-r, --recursive copy directories recursively
--remove-destination remove each existing destination file before attempting to open it (contrast with --force)
--strip-trailing-slashes remove any trailing slashes from each SOURCE argument
-S, --suffix SUFFIX override the usual backup suffix, '~', with SUFFIX
-s, --symbolic-link make symbolic links instead of copying
-t, --target-directory string copy 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
Copy a file to a new name
cpx notes.txt notes.bakCopy several files into a directory, reporting each one
cpx -v a.txt b.txt backup/Archive a directory tree, preserving modes, times and links
cpx -a project/ /mnt/backup/projectUpdate a mirror, copying only files that are newer
cpx -ru src/. mirror/Copy into a directory named first, without overwriting anything
cpx -n -t ~/Documents report.pdf slides.pdfAsk before overwriting an existing copy
cpx -i config.yml config.yml.origKeep the mode and timestamps of a script while copying it
cpx -p deploy.sh bin/Preserve only the timestamps, or archive without carrying over ownership
cpx --preserve=timestamps photo.jpg archive/ && cpx -a --no-preserve=ownership project/ copy/Recreate the source paths under a backup directory
cpx --parents src/app/main.go src/lib/util.go backup/Make a new release tree of hard links that share the old one's data
cpx -al releases/v1 releases/v2Create a symbolic link instead of a copy (use an absolute source)
cpx -s "$PWD/config.yml" config-link.ymlCopy a symbolic link as a link, rather than the file it points to
cpx -P current.yml saved-link.ymlCopy a tree, replacing every symbolic link with the file it points to
cpx -rL vendor/ vendor-flat/Copy through a symlinked directory named on the command line only
cpx -rH latest snapshotCopy a template's contents into an existing directory, not inside it
cpx -rT template/ newproject/Add missing default files without overwriting customized ones
cpx -r --update=none defaults/. config/Replace a read-only destination file
cpx -f new.conf readonly.confBack up a tree without crossing into other mounted file systems
cpx -ax --strip-trailing-slashes data/ /mnt/backup/dataMake a backup and continue only if the copy succeeded
cpx config.yml config.yml.bak && echox "backup saved"Copy every .conf file into a fresh directory with the gnux shell
gnux shell -c 'mkdirx -p confbak && cpx -v *.conf confbak/'Replace a symbolic link with a real copy instead of writing through it
cpx --remove-destination config/base.conf current.confUpdate a config file but keep the previous version as config.yml~
cpx -b new/config.yml config.ymlKeep every earlier version of a deployed file as app.conf.1, app.conf.2, ...
cpx --backup=numbered build/app.conf /etc/app/app.confOptions
Each option has a page of its own, with its usage and examples.
- -a, --archive: Same as
-dR --preserve=all. - --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. - -L, --dereference: Always follow symbolic links in SOURCE.
- -H, --dereference-args: Follow command-line symbolic links in SOURCE.
- -f, --force: If an existing destination file cannot be opened, remove it and try again.
- -i, --interactive: Prompt before overwrite.
- -l, --link: Hard
linkfiles instead of copying. - -n, --no-clobber: Do not overwrite an existing file.
- -P, --no-dereference: Never follow symbolic links in SOURCE.
- -d, --no-dereference-links: Same as
--no-dereference --preserve=links. - --no-preserve: Don't preserve the listed attributes.
- -T, --no-target-directory: Treat DEST as a normal file.
- -x, --one-file-system: Stay on this file system.
- --parents: Use the full source file name under DIRECTORY.
- --preserve: Preserve the listed attributes: mode, ownership, timestamps, links, all.
- -p, --preserve-default: Same as
--preserve=mode,ownership,timestamps. - --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. - -r, --recursive: Copy directories recursively.
- --remove-destination: Remove each existing destination file before attempting to open it (contrast with
--force). - --strip-trailing-slashes: Remove any trailing slashes from each SOURCE argument.
- -S, --suffix: Override the usual backup suffix, '~', with SUFFIX.
- -s, --symbolic-link: Make symbolic links instead of copying.
- -t, --target-directory: Copy 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
cpx --help # options, first examples, exit status
gnux help cpx # this page: the full manual
gnux help cpx --OPTION # one option in depth, with its examples