← Full reference

cp

Copy files and directories — with permissions, owners, timestamps and links

cp copies files and (with -r) directories. The new copy is a separate file with its own inode: changes to it don't affect the original. The sandbox has GNU coreutils 9.4.

Syntax

cp [options] source destination          # one file → a new name or into a directory
cp [options] source… directory/           # several files → into a directory
cp [options] -t directory source…         # same, directory first (handy for xargs)
cp -r [options] directory destination        # a whole directory

If destination is an existing directory, the copy goes inside it under the same name. Otherwise the file destination is created (or overwritten).

Options

Directories and links

OptionWhat it does
-r, -Rcopy directories recursively. Symbolic links inside are copied as links
-Lcopy the files links point to instead of the links
-Pcopy links as links (with -r this is the default anyway)
-Hfollow links only from the command line
-ldon't copy data, make hard links instead
-smake symbolic links (give the source as an absolute path, see below)
-xstay on the source's filesystem
--parentsrecreate the source path inside the destination directory: cp --parents a/b/f out/ → out/a/b/f
-t directorythe destination directory is given up front; all other arguments are sources
-Ttreat the destination as a plain name even if it's an existing directory

What to preserve

OptionWhat it does
(default)owner — whoever copies; timestamp — the current time; permissions — as the source minus umask. If the destination file already existed, its permissions and owner don't change
-ppreserve permissions, owner and group (if you have the rights), access and modification times
--preserve=LISTselectively: mode, ownership, timestamps, links, context, xattr, all
--no-preserve=modethe opposite: don't carry over what's listed
-aarchive mode: -r + -P + --preserve=all. For backups and moving directories "as is"

Overwriting

OptionWhat it does
-iask before overwriting
-ndon't overwrite existing files (in 9.4 it prints a portability warning; the new form is --update=none)
-ucopy only if the source is newer than the destination or the destination doesn't exist (--update=older)
-fif the destination file can't be opened for writing (e.g. it has mode 444), delete it and create it again
-bback up the file being replaced (file~); --backup=numbered — file.~1~, file.~2~…
-S suffixbackup suffix instead of ~

Other

OptionWhat it does
-vprint every action: 'x' -> 'z'
--sparse=alwaysmake a sparse file, skipping zeros (default auto)
--reflink=autoa CoW copy if the filesystem supports it (btrfs, xfs), otherwise a regular one

Source directory: src, src/ and src/.

Commanddst doesn't existdst already exists
cp -r src dstdst is created = a copy of srcdst/src appears
cp -r src/ dstsamesame: dst/src
cp -r src/. dstdst is created = a copy of srcthe contents of src land directly in dst

Unlike rsync, a trailing slash on the source changes nothing for cp. "The directory's contents, not the directory itself" is src/..

Examples

# a backup copy of a config next to it
cp /etc/hosts /etc/hosts.bak

# a whole directory, with permissions, owners, timestamps and links
cp -a /srv/app /srv/app.backup

# a directory's contents into an existing directory
cp -a /srv/app/. /mnt/new-app/

# several files into a directory, with a report
cp -v *.conf /etc/myapp/

# don't touch files that already exist in the destination
cp -r --update=none defaults/. /etc/myapp/

# update only changed files
cp -ru src/. mirror/

# preserve the directory structure
mkdir -p /tmp/out && cp --parents etc/app/app.conf /tmp/out/

# from find: set the destination directory with -t
find . -name '*.log' -print0 | xargs -0 cp -t /tmp/logs/

# a file whose name starts with a dash
cp -- -report.txt report.txt

Pitfalls

  • Without -r a directory isn't copied: "-r not specified; omitting directory". The exit code is 1.
  • Running cp -r src dst again doesn't update dst but creates dst/src: on the second run dst already exists. For syncing use src/. or rsync.
  • Without -p/-a the owner and timestamps are lost. Even root copying someone else's file gets a file owned by root with the current time.
  • An existing file's permissions don't change. cp into an existing file overwrites only the contents; permissions and owner stay the old ones.
  • cp file nonexistent_dir/ — error "Not a directory". Without the trailing slash the same call silently creates a file with that name.
  • Silent overwrite. Without -i/-n, cp overwrites the destination without asking (an interactive shell sometimes has a cp -i alias; scripts don't).
  • -n returns 0 even if nothing was copied — a script won't notice.
  • cp -s with a relative source works only if the link is created in the current directory; otherwise — "can make relative symbolic links only in current directory". Give the source as an absolute path.

See also

mv · rsync · ln · rm · tar · umask · mkdir