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
| Option | What it does |
|---|
-r, -R | copy directories recursively. Symbolic links inside are copied as links |
-L | copy the files links point to instead of the links |
-P | copy links as links (with -r this is the default anyway) |
-H | follow links only from the command line |
-l | don't copy data, make hard links instead |
-s | make symbolic links (give the source as an absolute path, see below) |
-x | stay on the source's filesystem |
--parents | recreate the source path inside the destination directory: cp --parents a/b/f out/ → out/a/b/f |
-t directory | the destination directory is given up front; all other arguments are sources |
-T | treat the destination as a plain name even if it's an existing directory |
What to preserve
| Option | What 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 |
-p | preserve permissions, owner and group (if you have the rights), access and modification times |
--preserve=LIST | selectively: mode, ownership, timestamps, links, context, xattr, all |
--no-preserve=mode | the opposite: don't carry over what's listed |
-a | archive mode: -r + -P + --preserve=all. For backups and moving directories "as is" |
Overwriting
| Option | What it does |
|---|
-i | ask before overwriting |
-n | don't overwrite existing files (in 9.4 it prints a portability warning; the new form is --update=none) |
-u | copy only if the source is newer than the destination or the destination doesn't exist (--update=older) |
-f | if the destination file can't be opened for writing (e.g. it has mode 444), delete it and create it again |
-b | back up the file being replaced (file~); --backup=numbered — file.~1~, file.~2~… |
-S suffix | backup suffix instead of ~ |
Other
| Option | What it does |
|---|
-v | print every action: 'x' -> 'z' |
--sparse=always | make a sparse file, skipping zeros (default auto) |
--reflink=auto | a CoW copy if the filesystem supports it (btrfs, xfs), otherwise a regular one |
Source directory: src, src/ and src/.
| Command | dst doesn't exist | dst already exists |
|---|
cp -r src dst | dst is created = a copy of src | dst/src appears |
cp -r src/ dst | same | same: dst/src |
cp -r src/. dst | dst is created = a copy of src | the 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