:   '''[file] copy''' ?'''-force'''? ?'''--'''? ''source target''

    :   '''[file] copy''' ?'''-force'''? ?'''--'''? ''source'' ?''source'' ...? ''targetDir''

The first form makes a copy of the file or directory ''source'' under the pathname ''target''. If ''target'' is an existing directory, then the second form is used. The second form makes a copy inside ''targetDir'' of each ''source'' file listed. If a directory is specified as a source, then the contents of the directory will be recursively copied into ''targetDir''. Existing files will not be overwritten unless the '''-force''' option is specified. When copying within a single filesystem, '''file copy''' will copy soft links (i.e. the links themselves are copied, not the things they point to). Trying to overwrite a non-empty directory, overwrite a directory with a file, or a file with a directory will all result in errors even if '''-force''' was specified. Arguments are processed in the order specified, halting at the first error, if any. A '''--''' marks the end of switches; the argument following the '''--''' will be treated as a source even if it starts with a `-`.

----
<<discussion>>
Trap: For soft-links this command copies the link and not the file the link refers to. Example:

 # touch a ; ln -s a b
 # ls -l a b
 ... 0 a
 ... 1 b -> a
 # tclsh
 % file copy b c ; exit
 # ls -l a b c
 ... 0 a
 ... 1 b -> a
 ... 1 c -> a

----
Question: How do I recursively copy from one directory structure to another that already exists?

file copy will not recursively overwrite:

 % file copy -force /home/path1/dirs /home/path2
 % file copy -force /home/path1/dirs /home/path2
 error copying "/home/path1/dirs" to "/home/path2/dirs": file already exists

Contrast with the following UNIX command that does not raise an error:

 # cp -rf /home/path1/dirs/* /home/path2/dirs

----
[gaoithe]: It was not obvious to me how to properly check for file copy error.  One simply '''[catch]'''es calls to file copy (same for other [file] commands such as stat).

======
if {[catch {file copy -force $sFrom $sTo} sError]} {
   FAIL "file copy failed: err:$sError to:$sTo"
}
======

----
[AMG]:  In Tcl 8.6, running [[file copy]] with no arguments produces this error message:

======none
wrong # args: should be "file copy ?-option value ...? source ?source ...? target"
======

Only two possible options are defined, `-force` and `--`, and neither takes an argument.  Additionally, `--`, if specified, must be the last option.  So I think the error message should instead be:

======none
wrong # args: should be "file copy ?-force? ?--? source ?source ...? target"
======

I'm not sure if this is considered a bug.  The behavior is technically correct but could be improved.  So I'm reporting it here rather than on the bug tracker.  I haven't checked the source, but it could be that [[file copy]] shares the Tcl_WrongNumArgs() invocation with lots of other commands in the ensemble, and there aren't enough hooks to customize the option descriptions.  If that's the case, "fixing" this could well be more trouble than it's worth.

<<discussion>>

----
**See also**
   * [file delete]
   * [file rename]

<<categories>> Tcl syntax help | Command