Skip to Content
gnux

cpx

Copy files and directories.

Mirrors GNU cp. Run it as cpx, or as gnux cpx.

Synopsis

cpx [OPTION]... SOURCE... DIRECTORY

GNU 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 -u so 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 exit

Examples

Copy a file to a new name

cpx notes.txt notes.bak

Copy several files into a directory, reporting each one

cpx -v a.txt b.txt backup/
cpx -a project/ /mnt/backup/project

Update 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.pdf

Ask before overwriting an existing copy

cpx -i config.yml config.yml.orig

Keep 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/
cpx -al releases/v1 releases/v2
cpx -s "$PWD/config.yml" config-link.yml
cpx -P current.yml saved-link.yml
cpx -rL vendor/ vendor-flat/

Copy through a symlinked directory named on the command line only

cpx -rH latest snapshot

Copy 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.conf

Back up a tree without crossing into other mounted file systems

cpx -ax --strip-trailing-slashes data/ /mnt/backup/data

Make 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/'
cpx --remove-destination config/base.conf current.conf

Update a config file but keep the previous version as config.yml~

cpx -b new/config.yml config.yml

Keep every earlier version of a deployed file as app.conf.1, app.conf.2, ...

cpx --backup=numbered build/app.conf /etc/app/app.conf

Options

Each option has a page of its own, with its usage and examples.

Exit status

StatusMeaning
0success: every operand was processed
1failure: 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

See also

On this page