FileUtils

Namespace for file utility methods for copying, moving, removing, etc.

What’s Here

First, what’s elsewhere. Module FileUtils:

• Inherits from class Object.

• Supplements class File (but is not included or extended there).

Here, module FileUtils provides methods that are useful for:

• Creating.

• Deleting.

• Querying.

• Setting.

• Comparing.

• Copying.

• Moving.

• Options.

Creating

• ::mkdir: Creates directories.

• ::mkdir_p, ::makedirs, ::mkpath: Creates directories, also creating ancestor directories as needed.

• ::link_entry: Creates a hard link.

• ::ln, ::link: Creates hard links.

• ::ln_s, ::symlink: Creates symbolic links.

• ::ln_sf: Creates symbolic links, overwriting if necessary.

• ::ln_sr: Creates symbolic links relative to targets

Deleting

• ::remove_dir: Removes a directory and its descendants.

• ::remove_entry: Removes an entry, including its descendants if it is a directory.

• ::remove_entry_secure: Like ::remove_entry, but removes securely.

• ::remove_file: Removes a file entry.

• ::rm, ::remove: Removes entries.

• ::rm_f, ::safe_unlink: Like ::rm, but removes forcibly.

• ::rm_r: Removes entries and their descendants.

• ::rm_rf, ::rmtree: Like ::rm_r, but removes forcibly.

• ::rmdir: Removes directories.

Querying

• ::pwd, ::getwd: Returns the path to the working directory.

• ::uptodate?: Returns whether a given entry is newer than given other entries.

Setting

• ::cd, ::chdir: Sets the working directory.

• ::chmod: Sets permissions for an entry.

• ::chmod_R: Sets permissions for an entry and its descendants.

• ::chown: Sets the owner and group for entries.

• ::chown_R: Sets the owner and group for entries and their descendants.

• ::touch: Sets modification and access times for entries, creating if necessary.

Comparing

• ::compare_file, ::cmp, ::identical?: Returns whether two entries are identical.

• ::compare_stream: Returns whether two streams are identical.

Copying

• ::copy_entry: Recursively copies an entry.

• ::copy_file: Copies an entry.

• ::copy_stream: Copies a stream.

• ::cp, ::copy: Copies files.

• ::cp_lr: Recursively creates hard links.

• ::cp_r: Recursively copies files, retaining mode, owner, and group.

• ::install: Recursively copies files, optionally setting mode, owner, and group.

Moving

• ::mv, ::move: Moves entries.

Options

• ::collect_method: Returns the names of methods that accept a given option.

• ::commands: Returns the names of methods that accept options.

• ::have_option?: Returns whether a given method accepts a given option.

• ::options: Returns all option names.

• ::options_of: Returns the names of the options for a given method.

Path Arguments

Some methods in FileUtils accept path arguments, which are interpreted as paths to filesystem entries:

• If the argument is a string, that value is the path.

• If the argument has method :to_path, it is converted via that method.

• If the argument has method :to_str, it is converted via that method.

About the Examples

Some examples here involve trees of file entries. For these, we sometimes display trees using the tree command-line utility, which is a recursive directory-listing utility that produces a depth-indented listing of files and directories.

We use a helper method to launch the command and control the format:

def tree(dirpath = '.')
  command = "tree --noreport --charset=ascii #{dirpath}"
  system(command)
end

To illustrate:

tree('src0')
# => src0
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt

Avoiding the TOCTTOU Vulnerability

For certain methods that recursively remove entries, there is a potential vulnerability called the Time-of-check to time-of-use, or TOCTTOU, vulnerability that can exist when:

• An ancestor directory of the entry at the target path is world writable; such directories include /tmp.

• The directory tree at the target path includes:

  • A world-writable descendant directory.

  • A symbolic link.

To avoid that vulnerability, you can use this method to remove entries:

• FileUtils.remove_entry_secure: removes recursively if the target path points to a directory.

Also available are these methods, each of which calls FileUtils.remove_entry_secure:

• FileUtils.rm_r with keyword argument secure: true.

• FileUtils.rm_rf with keyword argument secure: true.

Finally, this method for moving entries calls FileUtils.remove_entry_secure if the source and destination are on different file systems (which means that the “move” is really a copy and remove):

• FileUtils.mv with keyword argument secure: true.

Method FileUtils.remove_entry_secure removes securely by applying a special pre-process:

• If the target path points to a directory, this method uses methods File#chown and File#chmod in removing directories.

• The owner of the target directory should be either the current process or the super user (root).

WARNING: You must ensure that ALL parent directories cannot be moved by other untrusted users. For example, parent directories should not be owned by untrusted users, and should not be world writable except when the sticky bit is set.

For details of this security vulnerability, see Perl cases:

• CVE-2005-0448.

• CVE-2004-0452.