FileCopy

Copies one or more files.

FileCopy SourcePattern, DestPattern , Overwrite

Parameters

SourcePattern

Type: String

The name of a single file or folder, or a wildcard pattern such as C:\Temp\*.tmp. SourcePattern is assumed to be in A_WorkingDir if an absolute path isn't specified.

DestPattern

Type: String

The name or pattern of the destination, which is assumed to be in A_WorkingDir if an absolute path isn't specified.

If present, the first asterisk (*) in the filename is replaced with the source filename excluding its extension, while the first asterisk after the last full stop (.) is replaced with the source file's extension. If an asterisk is present but the extension is omitted, the source file's extension is used.

To perform a simple copy -- retaining the existing file name(s) -- specify only the folder name as shown in these mostly equivalent examples:

FileCopy "C:\*.txt", "C:\My Folder"
FileCopy "C:\*.txt", "C:\My Folder\*.*"

The destination directory must already exist. If My Folder does not exist, the first example above will use "My Folder" as the target filename, while the second example will copy no files.

Overwrite

Type: Integer (boolean)

This parameter determines whether to overwrite files if they already exist. If this parameter is 1 (true), the function overwrites existing files. If omitted or 0 (false), the function does not overwrite existing files.

Error Handling

An exception is thrown if any files failed to be copied, and Exception.Extra is set to the number of failures. If no files were found, an exception is thrown only if SourcePattern lacks the wildcards * and ?. In other words, copying a wildcard pattern such as "*.txt" is considered a success when it does not match any files.

Unlike FileMove, copying a file onto itself is always counted as an error, even if the overwrite mode is in effect.

If files were found, A_LastError is set to 0 (zero) or the result of the operating system's GetLastError() function immediately after the last failure. Otherwise A_LastError contains an error code that might indicate why no files were found.

Remarks

FileCopy copies files only. To instead copy the contents of a folder (all its files and subfolders), see the examples section below. To copy a single folder (including its subfolders), use DirCopy.

The operation will continue even if error(s) are encountered.

Related

FileMove, DirCopy, DirMove, FileDelete

Examples

#1

FileCopy "C:\My Documents\List1.txt", "D:\Main Backup\"  ; Make a copy but keep the orig. file name.
FileCopy "C:\My File.txt", "C:\My File New.txt"  ; Copy a file into the same folder by providing a new name.
FileCopy "C:\Folder1\*.txt", "D:\New Folder\*.bkp"  ; Copy to new location and give new extension.

#2: The following example copies all files and folders inside a folder to a different folder:

ErrorCount := CopyFilesAndFolders("C:\My Folder\*.*", "D:\Folder to receive all files & folders")
if ErrorCount != 0
    MsgBox ErrorCount " files/folders could not be copied."

CopyFilesAndFolders(SourcePattern, DestinationFolder, DoOverwrite := false)
; Copies all files and folders matching SourcePattern into the folder named DestinationFolder and
; returns the number of files/folders that could not be copied.
{
    ErrorCount := 0
    ; First copy all the files (but not the folders):
    try
        FileCopy SourcePattern, DestinationFolder, DoOverwrite
    catch Err
        ErrorCount := Err.Extra
    ; Now copy all the folders:
    Loop Files, SourcePattern, "D"  ; D means "retrieve folders only".
    {
        try
            DirCopy A_LoopFilePath, DestinationFolder "\" A_LoopFileName, DoOverwrite
        catch
        {
            ErrorCount += 1
            ; Report each problem folder by name.
            MsgBox "Could not copy " A_LoopFilePath " into " DestinationFolder
        }
    }
    return ErrorCount
}