Moving, Copying and Deleting Files

File and Stream Guide: [ nsIScriptableIO | Accessing Files | Getting File Information | Reading from Files | Writing to Files | Moving, Copying and Deleting Files | Uploading and Downloading Files | Working With Directories ]

Other documentation on files and I/O not using the unavailable nsIScriptableIO APIs: Code snippets: File I/O, Open and Save Dialogs, Reading textual data, Writing textual data, List of file-related error codes.

There are several methods of the nsIFile object which may be used to move and copy files on disk. nsIFile.copyTo() is used to copy a file, while nsIFile.moveTo() is used to move files. nsIFile.remove() may be used to delete a file.

Copying a File

nsIFile.copyTo() is used to copy files or directories, and should be called on the source file to copy. This method takes two arguments, the first is the destination directory in which to copy the file to, and the second argument is the new name of the file, if you wish to rename it in its new location. If you do not want to rename the file, and use the same name as the source file, use a null string for the second argument.

var file = IO.newFile("Home", "source.txt");
var destination = IO.newFile("Desktop", "");
file.copyTo(destination, "destination.txt");

This example copies a file called 'source.txt' within the user's home directory to the desktop. In addition, the file is renamed to 'destination.txt'. Two file objects are created, the first is the file to copy, and the second is the directory in which to copy the file to. nsIFile.copyTo() of the former is called, passing the latter as the first argument to nsIFile.copyTo(). Naturally, the destination must be a directory or an error will occur.

In this case, we assume that 'source.txt' is a file. If the item to copy is a directory, it can be copied in the same manner as above without changes. This allows an entire directory and its contents to be copied from one location to another. You might use this to make a backup of a directory of files for instance.

var file = IO.newFile("Home", "importantData");
var destination = IO.newFile("Desktop", "");
destination.append("backups");
file.copyTo(destination, "");

This example copies an item called 'importantData' into a directory called 'backups' within the desktop directory. nsIFile.append() is used to retrieve the 'backups' subdirectory. This method is used to navigate into subdirectories. For more information about nsIFile.append(), see Working with Directories.

In this last example, the destination filename is set to an empty string. This causes the item to be copied without changing its name. This will be the usual behaviour when copying to a different directory, but you would want to specify a filename when copying a file to another name within the same directory. In this latter situation, you may also omit the destination directory.

var file = IO.newFile("Desktop", "myimage.png");
file.copyTo(null, "anotherimage.png");

Here, a file is copied within the same directory as the supplied destination is null.

A number of errors could occur when copying a file, for instance if the file to copy does not exist or the destination directory is not writable. It is a good idea to enclose file operations within a try-catch block in order to capture any errors that might occur. For a list of possible file related errors, see File Errors.

Moving a File

To move a file, nsIFile.moveTo() may be used which functions similarly to nsIFile.copyTo(). The following example moves a file 'myfile.txt' in the user's home directory into the temporary directory. As with nsIFile.copyTo(), nsIFile.moveTo() takes two arguments, the destination directory and the new filename. If you do not want to rename the file and keep its existing name, use a null string for the second argument.

var file = IO.newFile("Home", "myfile.txt");
var destination = IO.newFile("Temporary", "");
file.moveTo(destination, "");

The second argument to nsIFile.moveTo() is an empty string to indicate that the same filename should be used. Specify a name for this argument to modify the filename while moving. This would be used when renaming a file within the same directory. When moving a file within the same directory, the destination argument may be null. For instance, the following example renames a file within the same directory:

file.moveTo(null, "hello.txt");

If the destination file already exists, nsIFile.moveTo() replaces the existing file. For this reason, you may wish to check if the file exists using nsIFile.exists() before moving the file.

Deleting a File

To delete a file, use nsIFile.remove(). This method takes one boolean argument which indicates whether to delete recursively or not. If true and the file object refers to a directory, the directory will be removed as well all files and subdirectories within it. If false, a directory will only be removed if it is empty. If the directory is not empty, an error will occur. For files, the argument is simply ignored.

var file = IO.newFile("Home", "photo.jpg");
file.remove(false);

This example removes the file called 'photo.jpg'.