Moving, Copying and Deleting Files

  • Revision slug: FileGuide/MoveCopyDelete
  • Revision title: Moving, Copying and Deleting Files
  • Revision id: 98992
  • Created:
  • Creator: trevorh
  • Is current revision? No
  • Comment Update to use templates; 102 words added, 46 words removed

Revision Content

Moving, Copying and Deleting Files

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

Copying a File

{{ifmethod("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. {{ifmethod("nsIFile","copyTo")} of the former is called, passing the latter as the first argument to {{ifmethod("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. {{ifmethod("nsIFile","append")} is used to retrieve the 'backups' subdirectory. This method is used to navigate into subdirectories. For more information about {{ifmethod("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, {{ifmethod("nsIFile","moveTo")} may be used which functions similarly to {{ifmethod("nsIFile","copyTo")}. The following example moves a file 'myfile.txt' in the user's home directory into the temporary directory. As with {{ifmethod("nsIFile","copyTo")}, {{ifmethod("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 {{ifmethod("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, {{ifmethod("nsIFile","moveTo")} replaces the existing file. For this reason, you may wish to check if the file exists using {{ifmethod("nsIFile","exists")} before moving the file.

Deleting a File

To delete a file, use {{ifmethod("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'.

{{ languages( { "ja": "ja/FileGuide/MoveCopyDelete" } ) }}

Revision Source

<h3 name="Moving.2C_Copying_and_Deleting_Files">Moving, Copying and Deleting Files</h3>
<p>There are several methods of the {{ interface("nsIFile") }} object which may be used to move and copy files on disk. {{ifmethod("nsIFile","copyTo")} is used to copy a file, while {{ifmethod("nsIFile","moveTo")} is used to move files. {{ifmethod("nsIFile","remove")} may be used to delete a file.</p>
<h4 name="Copying_a_File">Copying a File</h4>
<p>{{ifmethod("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.</p>
<pre class="brush: js">var file = IO.newFile("Home", "source.txt");
var destination = IO.newFile("Desktop", "");
file.copyTo(destination, "destination.txt");
</pre>
<p>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. {{ifmethod("nsIFile","copyTo")} of the former is called, passing the latter as the first argument to {{ifmethod("nsIFile","copyTo")}. Naturally, the destination must be a directory or an error will occur.</p>
<p>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.</p>
<pre class="brush: js">var file = IO.newFile("Home", "importantData");
var destination = IO.newFile("Desktop", "");
destination.append("backups");
file.copyTo(destination, "");
</pre>
<p>This example copies an item called 'importantData' into a directory called 'backups' within the desktop directory. {{ifmethod("nsIFile","append")} is used to retrieve the 'backups' subdirectory. This method is used to navigate into subdirectories. For more information about {{ifmethod("nsIFile","append")}, see <a href="/en/FileGuide/Directories" title="en/FileGuide/Directories">Working with Directories</a>.</p>
<p>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.</p>
<pre class="brush: js">var file = IO.newFile("Desktop", "myimage.png");
file.copyTo(null, "anotherimage.png");
</pre>
<p>Here, a file is copied within the same directory as the supplied destination is null.</p>
<p>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 <a href="/en/Table_Of_Errors#File_Errors" title="en/Table_Of_Errors#File_Errors">File Errors</a>.</p>
<h4 name="Moving_a_File">Moving a File</h4>
<p>To move a file, {{ifmethod("nsIFile","moveTo")} may be used which functions similarly to {{ifmethod("nsIFile","copyTo")}. The following example moves a file 'myfile.txt' in the user's home directory into the temporary directory. As with {{ifmethod("nsIFile","copyTo")}, {{ifmethod("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.</p>
<pre class="brush: js">var file = IO.newFile("Home", "myfile.txt");
var destination = IO.newFile("Temporary", "");
file.moveTo(destination, "");
</pre>
<p>The second argument to {{ifmethod("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:</p>
<pre class="brush: js">file.moveTo(null, "hello.txt");
</pre>
<p>If the destination file already exists, {{ifmethod("nsIFile","moveTo")} replaces the existing file. For this reason, you may wish to check if the file exists using {{ifmethod("nsIFile","exists")} before moving the file.</p>
<h4 name="Deleting_a_File">Deleting a File</h4>
<p>To delete a file, use {{ifmethod("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.</p>
<pre class="brush: js">var file = IO.newFile("Home", "photo.jpg");
file.remove(false);
</pre>
<p>This example removes the file called 'photo.jpg'.</p>

<p>{{ languages( { "ja": "ja/FileGuide/MoveCopyDelete" } ) }}</p>
Revert to this revision