module FileUtils - RDoc Documentation

# module FileUtils

# fileutils.rb¶ ↑

Copyright © 2000-2007 Minero Aoki

This program is free software. You can distribute/modify this program under the same terms of ruby.

## module `FileUtils`¶ ↑

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

### `Module` Functions¶ ↑

    require 'fileutils'

    FileUtils.cd(dir, **options)
    FileUtils.cd(dir, **options) {|dir| block }
    FileUtils.pwd()
    FileUtils.mkdir(dir, **options)
    FileUtils.mkdir(list, **options)
    FileUtils.mkdir_p(dir, **options)
    FileUtils.mkdir_p(list, **options)
    FileUtils.rmdir(dir, **options)
    FileUtils.rmdir(list, **options)
    FileUtils.ln(target, link, **options)
    FileUtils.ln(targets, dir, **options)
    FileUtils.ln_s(target, link, **options)
    FileUtils.ln_s(targets, dir, **options)
    FileUtils.ln_sf(target, link, **options)
    FileUtils.cp(src, dest, **options)
    FileUtils.cp(list, dir, **options)
    FileUtils.cp_r(src, dest, **options)
    FileUtils.cp_r(list, dir, **options)
    FileUtils.mv(src, dest, **options)
    FileUtils.mv(list, dir, **options)
    FileUtils.rm(list, **options)
    FileUtils.rm_r(list, **options)
    FileUtils.rm_rf(list, **options)
    FileUtils.install(src, dest, **options)
    FileUtils.chmod(mode, list, **options)
    FileUtils.chmod_R(mode, list, **options)
    FileUtils.chown(user, group, list, **options)
    FileUtils.chown_R(user, group, list, **options)
    FileUtils.touch(list, **options)

Possible `options` are:

`:force`

  forced operation (rewrite files if exist, remove directories if not empty, etc.);

`:verbose`

  print command to be run, in bash syntax, before performing it;

`:preserve`

  preserve object’s group, user and modification time on copying;

`:noop`

  no changes are made (usable in combination with `:verbose` which will print the command to run)

Each method documents the options that it honours. See also `::commands`, `::options` and `::options_of` methods to introspect which command have which options.

All methods that have the concept of a “source” file or directory can take either one file or a list of files in that argument. See the method documentation for examples.

There are some ‘low level’ methods, which do not accept keyword arguments:

    FileUtils.copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
    FileUtils.copy_file(src, dest, preserve = false, dereference = true)
    FileUtils.copy_stream(srcstream, deststream)
    FileUtils.remove_entry(path, force = false)
    FileUtils.remove_entry_secure(path, force = false)
    FileUtils.remove_file(path, force = false)
    FileUtils.compare_file(path_a, path_b)
    FileUtils.compare_stream(stream_a, stream_b)
    FileUtils.uptodate?(file, cmp_list)

## module `FileUtils::Verbose`¶ ↑

This module has all methods of `FileUtils` module, but it outputs messages before acting. This equates to passing the `:verbose` flag to methods in `FileUtils`.

## module `FileUtils::NoWrite`¶ ↑

This module has all methods of `FileUtils` module, but never changes files/directories. This equates to passing the `:noop` flag to methods in `FileUtils`.

## module `FileUtils::DryRun`¶ ↑

This module has all methods of `FileUtils` module, but never changes files/directories. This equates to passing the `:noop` and `:verbose` flags to methods in `FileUtils`.

### Constants

VERSION

### Public Class Methods

cd(dir, verbose: nil) { |dir| ... } click to toggle source

Changes the current directory to the directory `dir`.

If this method is called with block, resumes to the previous working directory after the block execution has finished.

    FileUtils.cd('/')  # change directory

    FileUtils.cd('/', verbose: true)   # change directory and report it

    FileUtils.cd('/') do  # change directory
      # ...               # do something
    end                   # return to original directory

    # File lib/fileutils.rb, line 137
    def cd(dir, verbose: nil, &block) # :yield: dir
      fu_output_message "cd #{dir}" if verbose
      result = Dir.chdir(dir, &block)
      fu_output_message 'cd -' if verbose and block
      result
    end

Also aliased as: chdir
chdir(dir, verbose: nil)
Alias for: cd
chmod(mode, list, noop: nil, verbose: nil) click to toggle source

Changes permission bits on the named files (in `list`) to the bit pattern represented by `mode`.

`mode` is the symbolic and absolute mode can be used.

Absolute mode is

    FileUtils.chmod 0755, 'somecommand'
    FileUtils.chmod 0644, %w(my.rb your.rb his.rb her.rb)
    FileUtils.chmod 0755, '/usr/bin/ruby', verbose: true

Symbolic mode is

    FileUtils.chmod "u=wrx,go=rx", 'somecommand'
    FileUtils.chmod "u=wr,go=rr", %w(my.rb your.rb his.rb her.rb)
    FileUtils.chmod "u=wrx,go=rx", '/usr/bin/ruby', verbose: true

“a”

  is user, group, other mask.

“u”

  is user’s mask.

“g”

  is group’s mask.

“o”

  is other’s mask.

“w”

  is write permission.

“r”

  is read permission.

“x”

  is execute permission.

“X”

  is execute permission for directories only, must be used in conjunction with “+”

“s”

  is uid, gid.

“t”

  is sticky bit.

“+”

  is added to a class given the specified mode.

“-”

  Is removed from a given class given mode.

“=”

  Is the exact nature of the class will be given a specified mode.

    # File lib/fileutils.rb, line 997
    def chmod(mode, list, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message sprintf('chmod %s %s', mode_to_s(mode), list.join(' ')) if verbose
      return if noop
      list.each do |path|
        Entry_.new(path).chmod(fu_mode(mode, path))
      end
    end

chmod_R(mode, list, noop: nil, verbose: nil, force: nil) click to toggle source

Changes permission bits on the named files (in `list`) to the bit pattern represented by `mode`.

    FileUtils.chmod_R 0700, "/tmp/app.#{$$}"
    FileUtils.chmod_R "u=wrx", "/tmp/app.#{$$}"

    # File lib/fileutils.rb, line 1014
    def chmod_R(mode, list, noop: nil, verbose: nil, force: nil)
      list = fu_list(list)
      fu_output_message sprintf('chmod -R%s %s %s',
                                (force ? 'f' : ''),
                                mode_to_s(mode), list.join(' ')) if verbose
      return if noop
      list.each do |root|
        Entry_.new(root).traverse do |ent|
          begin
            ent.chmod(fu_mode(mode, ent.path))
          rescue
            raise unless force
          end
        end
      end
    end

chown(user, group, list, noop: nil, verbose: nil) click to toggle source

Changes owner and group on the named files (in `list`) to the user `user` and the group `group`. `user` and `group` may be an ID (Integer/String) or a name (`String`). If `user` or `group` is nil, this method does not change the attribute.

    FileUtils.chown 'root', 'staff', '/usr/local/bin/ruby'
    FileUtils.chown nil, 'bin', Dir.glob('/usr/bin/*'), verbose: true

    # File lib/fileutils.rb, line 1042
    def chown(user, group, list, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message sprintf('chown %s %s',
                                (group ? "#{user}:#{group}" : user || ':'),
                                list.join(' ')) if verbose
      return if noop
      uid = fu_get_uid(user)
      gid = fu_get_gid(group)
      list.each do |path|
        Entry_.new(path).chown uid, gid
      end
    end

chown_R(user, group, list, noop: nil, verbose: nil, force: nil) click to toggle source

Changes owner and group on the named files (in `list`) to the user `user` and the group `group` recursively. `user` and `group` may be an ID (Integer/String) or a name (`String`). If `user` or `group` is nil, this method does not change the attribute.

    FileUtils.chown_R 'www', 'www', '/var/www/htdocs'
    FileUtils.chown_R 'cvs', 'cvs', '/var/cvs', verbose: true

    # File lib/fileutils.rb, line 1066
    def chown_R(user, group, list, noop: nil, verbose: nil, force: nil)
      list = fu_list(list)
      fu_output_message sprintf('chown -R%s %s %s',
                                (force ? 'f' : ''),
                                (group ? "#{user}:#{group}" : user || ':'),
                                list.join(' ')) if verbose
      return if noop
      uid = fu_get_uid(user)
      gid = fu_get_gid(group)
      list.each do |root|
        Entry_.new(root).traverse do |ent|
          begin
            ent.chown uid, gid
          rescue
            raise unless force
          end
        end
      end
    end

cmp(a, b)
Alias for: compare_file
collect_method(opt) click to toggle source

Returns an `Array` of methods names which have the option `opt`.

    p FileUtils.collect_method(:preserve) #=> ["cp", "cp_r", "copy", "install"]

    # File lib/fileutils.rb, line 1668
    def self.collect_method(opt)
      OPT_TABLE.keys.select {|m| OPT_TABLE[m].include?(opt) }
    end

commands() click to toggle source

Returns an `Array` of names of high-level methods that accept any keyword arguments.

    p FileUtils.commands  #=> ["chmod", "cp", "cp_r", "install", ...]

    # File lib/fileutils.rb, line 1629
    def self.commands
      OPT_TABLE.keys
    end

compare_file(a, b) click to toggle source

Returns true if the contents of a file `a` and a file `b` are identical.

    FileUtils.compare_file('somefile', 'somefile')       #=> true
    FileUtils.compare_file('/dev/null', '/dev/urandom')  #=> false

    # File lib/fileutils.rb, line 809
    def compare_file(a, b)
      return false unless File.size(a) == File.size(b)
      File.open(a, 'rb') {|fa|
        File.open(b, 'rb') {|fb|
          return compare_stream(fa, fb)
        }
      }
    end

Also aliased as: identical?, cmp
compare_stream(a, b) click to toggle source

Returns true if the contents of a stream `a` and `b` are identical.

    # File lib/fileutils.rb, line 827
    def compare_stream(a, b)
      bsize = fu_stream_blksize(a, b)

      sa = String.new(capacity: bsize)
      sb = String.new(capacity: bsize)

      begin
        a.read(bsize, sa)
        b.read(bsize, sb)
        return true if sa.empty? && sb.empty?
      end while sa == sb
      false
    end

copy(src, dest, preserve: nil, noop: nil, verbose: nil)
Alias for: cp
copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false) click to toggle source

Copies a file system entry `src` to `dest`. If `src` is a directory, this method copies its contents recursively. This method preserves file types, c.f. symlink, directory… (FIFO, device files and etc. are not supported yet)

Both of `src` and `dest` must be a path name. `src` must exist, `dest` must not exist.

If `preserve` is true, this method preserves owner, group, and modified time. Permissions are copied regardless `preserve`.

If `dereference_root` is true, this method dereference tree root.

If `remove_destination` is true, this method removes each destination file before copy.

    # File lib/fileutils.rb, line 482
    def copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
      if dereference_root
        src = File.realpath(src)
      end

      Entry_.new(src, nil, false).wrap_traverse(proc do |ent|
        destent = Entry_.new(dest, ent.rel, false)
        File.unlink destent.path if remove_destination && (File.file?(destent.path) || File.symlink?(destent.path))
        ent.copy destent.path
      end, proc do |ent|
        destent = Entry_.new(dest, ent.rel, false)
        ent.copy_metadata destent.path if preserve
      end)
    end

copy_file(src, dest, preserve = false, dereference = true) click to toggle source

Copies file contents of `src` to `dest`. Both of `src` and `dest` must be a path name.

    # File lib/fileutils.rb, line 502
    def copy_file(src, dest, preserve = false, dereference = true)
      ent = Entry_.new(src, nil, dereference)
      ent.copy_file dest
      ent.copy_metadata dest if preserve
    end

copy_stream(src, dest) click to toggle source

Copies stream `src` to `dest`. `src` must respond to read(n) and `dest` must respond to write(str).

    # File lib/fileutils.rb, line 514
    def copy_stream(src, dest)
      IO.copy_stream(src, dest)
    end

cp(src, dest, preserve: nil, noop: nil, verbose: nil) click to toggle source

Copies a file content `src` to `dest`. If `dest` is a directory, copies `src` to `dest/src`.

If `src` is a list of files, then `dest` must be a directory.

    FileUtils.cp 'eval.c', 'eval.c.org'
    FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6'
    FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6', verbose: true
    FileUtils.cp 'symlink', 'dest'   # copy content, "dest" is not a symlink

    # File lib/fileutils.rb, line 419
    def cp(src, dest, preserve: nil, noop: nil, verbose: nil)
      fu_output_message "cp#{preserve ? ' -p' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest(src, dest) do |s, d|
        copy_file s, d, preserve
      end
    end

Also aliased as: copy
cp_lr(src, dest, noop: nil, verbose: nil, dereference_root: true, remove_destination: false) click to toggle source

Hard link `src` to `dest`. If `src` is a directory, this method links all its contents recursively. If `dest` is a directory, links `src` to `dest/src`.

`src` can be a list of files.

If `dereference_root` is true, this method dereference tree root.

If `remove_destination` is true, this method removes each destination file before copy.

    FileUtils.rm_r site_ruby + '/mylib', force: true
    FileUtils.cp_lr 'lib/', site_ruby + '/mylib'

    # Examples of linking several files to target directory.
    FileUtils.cp_lr %w(mail.rb field.rb debug/), site_ruby + '/tmail'
    FileUtils.cp_lr Dir.glob('*.rb'), '/home/aamine/lib/ruby', noop: true, verbose: true

    # If you want to link all contents of a directory instead of the
    # directory itself, c.f. src/x -> dest/x, src/y -> dest/y,
    # use the following code.
    FileUtils.cp_lr 'src/.', 'dest'  # cp_lr('src', 'dest') makes dest/src, but this doesn't.

    # File lib/fileutils.rb, line 332
    def cp_lr(src, dest, noop: nil, verbose: nil,
              dereference_root: true, remove_destination: false)
      fu_output_message "cp -lr#{remove_destination ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest(src, dest) do |s, d|
        link_entry s, d, dereference_root, remove_destination
      end
    end

cp_r(src, dest, preserve: nil, noop: nil, verbose: nil, dereference_root: true, remove_destination: nil) click to toggle source

Copies `src` to `dest`. If `src` is a directory, this method copies all its contents recursively. If `dest` is a directory, copies `src` to `dest/src`.

`src` can be a list of files.

If `dereference_root` is true, this method dereference tree root.

If `remove_destination` is true, this method removes each destination file before copy.

    # Installing Ruby library "mylib" under the site_ruby
    FileUtils.rm_r site_ruby + '/mylib', force: true
    FileUtils.cp_r 'lib/', site_ruby + '/mylib'

    # Examples of copying several files to target directory.
    FileUtils.cp_r %w(mail.rb field.rb debug/), site_ruby + '/tmail'
    FileUtils.cp_r Dir.glob('*.rb'), '/home/foo/lib/ruby', noop: true, verbose: true

    # If you want to copy all contents of a directory instead of the
    # directory itself, c.f. src/x -> dest/x, src/y -> dest/y,
    # use following code.
    FileUtils.cp_r 'src/.', 'dest'     # cp_r('src', 'dest') makes dest/src,
                                       # but this doesn't.

    # File lib/fileutils.rb, line 456
    def cp_r(src, dest, preserve: nil, noop: nil, verbose: nil,
             dereference_root: true, remove_destination: nil)
      fu_output_message "cp -r#{preserve ? 'p' : ''}#{remove_destination ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest(src, dest) do |s, d|
        copy_entry s, d, preserve, dereference_root, remove_destination
      end
    end

getwd()
Alias for: pwd
have_option?(mid, opt) click to toggle source

Returns true if the method `mid` have an option `opt`.

    p FileUtils.have_option?(:cp, :noop)     #=> true
    p FileUtils.have_option?(:rm, :force)    #=> true
    p FileUtils.have_option?(:rm, :preserve) #=> false

    # File lib/fileutils.rb, line 1649
    def self.have_option?(mid, opt)
      li = OPT_TABLE[mid.to_s] or raise ArgumentError, "no such method: #{mid}"
      li.include?(opt)
    end

identical?(a, b)
Alias for: compare_file
install(src, dest, mode: nil, owner: nil, group: nil, preserve: nil, noop: nil, verbose: nil) click to toggle source

If `src` is not same as `dest`, copies it and changes the permission mode to `mode`. If `dest` is a directory, destination is `dest`/`src`. This method removes destination before copy.

    FileUtils.install 'ruby', '/usr/local/bin/ruby', mode: 0755, verbose: true
    FileUtils.install 'lib.rb', '/usr/local/lib/ruby/site_ruby', verbose: true

    # File lib/fileutils.rb, line 850
    def install(src, dest, mode: nil, owner: nil, group: nil, preserve: nil,
                noop: nil, verbose: nil)
      if verbose
        msg = +"install -c"
        msg << ' -p' if preserve
        msg << ' -m ' << mode_to_s(mode) if mode
        msg << " -o #{owner}" if owner
        msg << " -g #{group}" if group
        msg << ' ' << [src,dest].flatten.join(' ')
        fu_output_message msg
      end
      return if noop
      uid = fu_get_uid(owner)
      gid = fu_get_gid(group)
      fu_each_src_dest(src, dest) do |s, d|
        st = File.stat(s)
        unless File.exist?(d) and compare_file(s, d)
          remove_file d, true
          copy_file s, d
          File.utime st.atime, st.mtime, d if preserve
          File.chmod fu_mode(mode, st), d if mode
          File.chown uid, gid, d if uid or gid
        end
      end
    end

link(src, dest, force: nil, noop: nil, verbose: nil)
Alias for: ln
link_entry(src, dest, dereference_root = false, remove_destination = false) click to toggle source

Hard links a file system entry `src` to `dest`. If `src` is a directory, this method links its contents recursively.

Both of `src` and `dest` must be a path name. `src` must exist, `dest` must not exist.

If `dereference_root` is true, this method dereferences the tree root.

If `remove_destination` is true, this method removes each destination file before copy.

    # File lib/fileutils.rb, line 399
    def link_entry(src, dest, dereference_root = false, remove_destination = false)
      Entry_.new(src, nil, dereference_root).traverse do |ent|
        destent = Entry_.new(dest, ent.rel, false)
        File.unlink destent.path if remove_destination && File.file?(destent.path)
        ent.link destent.path
      end
    end

ln(target, link, force: nil, noop: nil, verbose: nil) click to toggle source
ln(target, dir, force: nil, noop: nil, verbose: nil)
ln(targets, dir, force: nil, noop: nil, verbose: nil)

In the first form, creates a hard link `link` which points to `target`. If `link` already exists, raises Errno::EEXIST. But if the `force` option is set, overwrites `link`.

    FileUtils.ln 'gcc', 'cc', verbose: true
    FileUtils.ln '/usr/bin/emacs21', '/usr/bin/emacs'

In the second form, creates a link `dir/target` pointing to `target`. In the third form, creates several hard links in the directory `dir`, pointing to each item in `targets`. If `dir` is not a directory, raises Errno::ENOTDIR.

    FileUtils.cd '/sbin'
    FileUtils.ln %w(cp mv mkdir), '/bin'   # Now /sbin/cp and /bin/cp are linked.

    # File lib/fileutils.rb, line 296
    def ln(src, dest, force: nil, noop: nil, verbose: nil)
      fu_output_message "ln#{force ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest0(src, dest) do |s,d|
        remove_file d, true if force
        File.link s, d
      end
    end

Also aliased as: link
ln_s(target, link, force: nil, noop: nil, verbose: nil) click to toggle source
ln_s(target, dir, force: nil, noop: nil, verbose: nil)
ln_s(targets, dir, force: nil, noop: nil, verbose: nil)

In the first form, creates a symbolic link `link` which points to `target`. If `link` already exists, raises Errno::EEXIST. But if the `force` option is set, overwrites `link`.

    FileUtils.ln_s '/usr/bin/ruby', '/usr/local/bin/ruby'
    FileUtils.ln_s 'verylongsourcefilename.c', 'c', force: true

In the second form, creates a link `dir/target` pointing to `target`. In the third form, creates several symbolic links in the directory `dir`, pointing to each item in `targets`. If `dir` is not a directory, raises Errno::ENOTDIR.

    FileUtils.ln_s Dir.glob('/bin/*.rb'), '/home/foo/bin'

    # File lib/fileutils.rb, line 362
    def ln_s(src, dest, force: nil, noop: nil, verbose: nil)
      fu_output_message "ln -s#{force ? 'f' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest0(src, dest) do |s,d|
        remove_file d, true if force
        File.symlink s, d
      end
    end

Also aliased as: symlink
ln_sf(*args) click to toggle source

Same as

    FileUtils.ln_s(*args, force: true)

    # File lib/fileutils.rb, line 383
    def ln_sf(src, dest, noop: nil, verbose: nil)
      ln_s src, dest, force: true, noop: noop, verbose: verbose
    end

makedirs(list, mode: nil, noop: nil, verbose: nil)
Alias for: mkdir_p
mkdir(list, mode: nil, noop: nil, verbose: nil) click to toggle source

Creates one or more directories.

    FileUtils.mkdir 'test'
    FileUtils.mkdir %w(tmp data)
    FileUtils.mkdir 'notexist', noop: true  # Does not really create.
    FileUtils.mkdir 'tmp', mode: 0700

    # File lib/fileutils.rb, line 180
    def mkdir(list, mode: nil, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message "mkdir #{mode ? ('-m %03o ' % mode) : ''}#{list.join ' '}" if verbose
      return if noop

      list.each do |dir|
        fu_mkdir dir, mode
      end
    end

mkdir_p(list, mode: nil, noop: nil, verbose: nil) click to toggle source

Creates a directory and all its parent directories. For example,

    FileUtils.mkdir_p '/usr/local/lib/ruby'

causes to make following directories, if they do not exist.

- /usr

- /usr/local

- /usr/local/lib

- /usr/local/lib/ruby

You can pass several directories at a time in a list.

    # File lib/fileutils.rb, line 206
    def mkdir_p(list, mode: nil, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message "mkdir -p #{mode ? ('-m %03o ' % mode) : ''}#{list.join ' '}" if verbose
      return *list if noop

      list.each do |item|
        path = remove_trailing_slash(item)

        stack = []
        until File.directory?(path) || File.dirname(path) == path
          stack.push path
          path = File.dirname(path)
        end
        stack.reverse_each do |dir|
          begin
            fu_mkdir dir, mode
          rescue SystemCallError
            raise unless File.directory?(dir)
          end
        end
      end

      return *list
    end

Also aliased as: mkpath, makedirs
mkpath(list, mode: nil, noop: nil, verbose: nil)
Alias for: mkdir_p
move(src, dest, force: nil, noop: nil, verbose: nil, secure: nil)
Alias for: mv
mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil) click to toggle source

Moves file(s) `src` to `dest`. If `file` and `dest` exist on the different disk partition, the file is copied then the original file is removed.

    FileUtils.mv 'badname.rb', 'goodname.rb'
    FileUtils.mv 'stuff.rb', '/notexist/lib/ruby', force: true  # no error

    FileUtils.mv %w(junk.txt dust.txt), '/home/foo/.trash/'
    FileUtils.mv Dir.glob('test*.rb'), 'test', noop: true, verbose: true

    # File lib/fileutils.rb, line 529
    def mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil)
      fu_output_message "mv#{force ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest(src, dest) do |s, d|
        destent = Entry_.new(d, nil, true)
        begin
          if destent.exist?
            if destent.directory?
              raise Errno::EEXIST, d
            end
          end
          begin
            File.rename s, d
          rescue Errno::EXDEV,
                 Errno::EPERM # move from unencrypted to encrypted dir (ext4)
            copy_entry s, d, true
            if secure
              remove_entry_secure s, force
            else
              remove_entry s, force
            end
          end
        rescue SystemCallError
          raise unless force
        end
      end
    end

Also aliased as: move
options() click to toggle source

Returns an `Array` of option names.

    p FileUtils.options  #=> ["noop", "force", "verbose", "preserve", "mode"]

    # File lib/fileutils.rb, line 1638
    def self.options
      OPT_TABLE.values.flatten.uniq.map {|sym| sym.to_s }
    end

options_of(mid) click to toggle source

Returns an `Array` of option names of the method `mid`.

    p FileUtils.options_of(:rm)  #=> ["noop", "verbose", "force"]

    # File lib/fileutils.rb, line 1659
    def self.options_of(mid)
      OPT_TABLE[mid.to_s].map {|sym| sym.to_s }
    end

pwd() click to toggle source

Returns the name of the current directory.

    # File lib/fileutils.rb, line 115
    def pwd
      Dir.pwd
    end

Also aliased as: getwd
remove(list, force: nil, noop: nil, verbose: nil)
Alias for: rm
remove_dir(path, force = false) click to toggle source

Removes a directory `dir` and its contents recursively. This method ignores `StandardError` if `force` is true.

    # File lib/fileutils.rb, line 798
    def remove_dir(path, force = false)
      remove_entry path, force   # FIXME?? check if it is a directory
    end

remove_entry(path, force = false) click to toggle source

This method removes a file system entry `path`. `path` might be a regular file, a directory, or something. If `path` is a directory, remove it recursively.

See also remove_entry_secure.

    # File lib/fileutils.rb, line 770
    def remove_entry(path, force = false)
      Entry_.new(path).postorder_traverse do |ent|
        begin
          ent.remove
        rescue
          raise unless force
        end
      end
    rescue
      raise unless force
    end

remove_entry_secure(path, force = false) click to toggle source

This method removes a file system entry `path`. `path` shall be a regular file, a directory, or something. If `path` is a directory, remove it recursively. This method is required to avoid TOCTTOU (time-of-check-to-time-of-use) local security vulnerability of rm_r. `rm_r` causes security hole when:

- Parent directory is world writable (including /tmp).

- Removing directory tree includes world writable directory.

- The system has symbolic link.

To avoid this security hole, this method applies special preprocess. If `path` is a directory, this method chown(2) and chmod(2) all removing directories. This requires the current process is the owner of the removing whole directory tree, or is 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 set.

WARNING: Only the owner of the removing directory tree, or Unix super user (root) should invoke this method. Otherwise this method does not work.

For details of this security vulnerability, see Perl’s case:

- cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2005-0448

- cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2004-0452

For fileutils.rb, this vulnerability is reported in [ruby-dev:26100].

    # File lib/fileutils.rb, line 677
    def remove_entry_secure(path, force = false)
      unless fu_have_symlink?
        remove_entry path, force
        return
      end
      fullpath = File.expand_path(path)
      st = File.lstat(fullpath)
      unless st.directory?
        File.unlink fullpath
        return
      end
      # is a directory.
      parent_st = File.stat(File.dirname(fullpath))
      unless parent_st.world_writable?
        remove_entry path, force
        return
      end
      unless parent_st.sticky?
        raise ArgumentError, "parent directory is world writable, FileUtils#remove_entry_secure does not work; abort: #{path.inspect} (parent directory mode #{'%o' % parent_st.mode})"
      end

      # freeze tree root
      euid = Process.euid
      dot_file = fullpath + "/."
      begin
        File.open(dot_file) {|f|
          unless fu_stat_identical_entry?(st, f.stat)
            # symlink (TOC-to-TOU attack?)
            File.unlink fullpath
            return
          end
          f.chown euid, -1
          f.chmod 0700
        }
      rescue Errno::EISDIR # JRuby in non-native mode can't open files as dirs
        File.lstat(dot_file).tap {|fstat|
          unless fu_stat_identical_entry?(st, fstat)
            # symlink (TOC-to-TOU attack?)
            File.unlink fullpath
            return
          end
          File.chown euid, -1, dot_file
          File.chmod 0700, dot_file
        }
      end

      unless fu_stat_identical_entry?(st, File.lstat(fullpath))
        # TOC-to-TOU attack?
        File.unlink fullpath
        return
      end

      # ---- tree root is frozen ----
      root = Entry_.new(path)
      root.preorder_traverse do |ent|
        if ent.directory?
          ent.chown euid, -1
          ent.chmod 0700
        end
      end
      root.postorder_traverse do |ent|
        begin
          ent.remove
        rescue
          raise unless force
        end
      end
    rescue
      raise unless force
    end

remove_file(path, force = false) click to toggle source

Removes a file `path`. This method ignores `StandardError` if `force` is true.

    # File lib/fileutils.rb, line 787
    def remove_file(path, force = false)
      Entry_.new(path).remove_file
    rescue
      raise unless force
    end

rm(list, force: nil, noop: nil, verbose: nil) click to toggle source

Remove file(s) specified in `list`. This method cannot remove directories. All StandardErrors are ignored when the :force option is set.

    FileUtils.rm %w( junk.txt dust.txt )
    FileUtils.rm Dir.glob('*.so')
    FileUtils.rm 'NotExistFile', force: true   # never raises exception

    # File lib/fileutils.rb, line 569
    def rm(list, force: nil, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message "rm#{force ? ' -f' : ''} #{list.join ' '}" if verbose
      return if noop

      list.each do |path|
        remove_file path, force
      end
    end

Also aliased as: remove
rm_f(list, noop: nil, verbose: nil) click to toggle source

Equivalent to

    FileUtils.rm(list, force: true)

    # File lib/fileutils.rb, line 588
    def rm_f(list, noop: nil, verbose: nil)
      rm list, force: true, noop: noop, verbose: verbose
    end

Also aliased as: safe_unlink
rm_r(list, force: nil, noop: nil, verbose: nil, secure: nil) click to toggle source

remove files `list`[0] `list`[1]… If `list`[n] is a directory, removes its all contents recursively. This method ignores `StandardError` when :force option is set.

    FileUtils.rm_r Dir.glob('/tmp/*')
    FileUtils.rm_r 'some_dir', force: true

WARNING: This method causes local vulnerability if one of parent directories or removing directory tree are world writable (including /tmp, whose permission is 1777), and the current process has strong privilege such as Unix super user (root), and the system has symbolic link. For secure removing, read the documentation of `remove_entry_secure` carefully, and set :secure option to true. Default is `secure: false`.

NOTE: This method calls `remove_entry_secure` if :secure option is set. See also remove_entry_secure.

    # File lib/fileutils.rb, line 615
    def rm_r(list, force: nil, noop: nil, verbose: nil, secure: nil)
      list = fu_list(list)
      fu_output_message "rm -r#{force ? 'f' : ''} #{list.join ' '}" if verbose
      return if noop
      list.each do |path|
        if secure
          remove_entry_secure path, force
        else
          remove_entry path, force
        end
      end
    end

rm_rf(list, noop: nil, verbose: nil, secure: nil) click to toggle source

Equivalent to

    FileUtils.rm_r(list, force: true)

WARNING: This method causes local vulnerability. Read the documentation of `rm_r` first.

    # File lib/fileutils.rb, line 637
    def rm_rf(list, noop: nil, verbose: nil, secure: nil)
      rm_r list, force: true, noop: noop, verbose: verbose, secure: secure
    end

Also aliased as: rmtree
rmdir(list, parents: nil, noop: nil, verbose: nil) click to toggle source

Removes one or more directories.

    FileUtils.rmdir 'somedir'
    FileUtils.rmdir %w(somedir anydir otherdir)
    # Does not really remove directory; outputs message.
    FileUtils.rmdir 'somedir', verbose: true, noop: true

    # File lib/fileutils.rb, line 256
    def rmdir(list, parents: nil, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message "rmdir #{parents ? '-p ' : ''}#{list.join ' '}" if verbose
      return if noop
      list.each do |dir|
        Dir.rmdir(dir = remove_trailing_slash(dir))
        if parents
          begin
            until (parent = File.dirname(dir)) == '.' or parent == dir
              dir = parent
              Dir.rmdir(dir)
            end
          rescue Errno::ENOTEMPTY, Errno::EEXIST, Errno::ENOENT
          end
        end
      end
    end

rmtree(list, noop: nil, verbose: nil, secure: nil)
Alias for: rm_rf
safe_unlink(list, noop: nil, verbose: nil)
Alias for: rm_f
symlink(src, dest, force: nil, noop: nil, verbose: nil)
Alias for: ln_s
touch(list, noop: nil, verbose: nil, mtime: nil, nocreate: nil) click to toggle source

Updates modification time (mtime) and access time (atime) of file(s) in `list`. Files are created if they don’t exist.

    FileUtils.touch 'timestamp'
    FileUtils.touch Dir.glob('*.c');  system 'make'

    # File lib/fileutils.rb, line 1122
    def touch(list, noop: nil, verbose: nil, mtime: nil, nocreate: nil)
      list = fu_list(list)
      t = mtime
      if verbose
        fu_output_message "touch #{nocreate ? '-c ' : ''}#{t ? t.strftime('-t %Y%m%d%H%M.%S ') : ''}#{list.join ' '}"
      end
      return if noop
      list.each do |path|
        created = nocreate
        begin
          File.utime(t, t, path)
        rescue Errno::ENOENT
          raise if created
          File.open(path, 'a') {
            ;
          }
          created = true
          retry if t
        end
      end
    end

uptodate?(new, old_list) click to toggle source

Returns true if `new` is newer than all `old_list`. Non-existent files are older than any file.

    FileUtils.uptodate?('hello.o', %w(hello.c hello.h)) or \
        system 'make hello.o'

    # File lib/fileutils.rb, line 155
    def uptodate?(new, old_list)
      return false unless File.exist?(new)
      new_time = File.mtime(new)
      old_list.each do |old|
        if File.exist?(old)
          return false unless new_time > File.mtime(old)
        end
      end
      true
    end

### Private Instance Methods

cd(dir, verbose: nil) { |dir| ... } click to toggle source

Changes the current directory to the directory `dir`.

If this method is called with block, resumes to the previous working directory after the block execution has finished.

    FileUtils.cd('/')  # change directory

    FileUtils.cd('/', verbose: true)   # change directory and report it

    FileUtils.cd('/') do  # change directory
      # ...               # do something
    end                   # return to original directory

    # File lib/fileutils.rb, line 137
    def cd(dir, verbose: nil, &block) # :yield: dir
      fu_output_message "cd #{dir}" if verbose
      result = Dir.chdir(dir, &block)
      fu_output_message 'cd -' if verbose and block
      result
    end

Also aliased as: chdir
chdir(dir, verbose: nil)
Alias for: cd
chmod(mode, list, noop: nil, verbose: nil) click to toggle source

Changes permission bits on the named files (in `list`) to the bit pattern represented by `mode`.

`mode` is the symbolic and absolute mode can be used.

Absolute mode is

    FileUtils.chmod 0755, 'somecommand'
    FileUtils.chmod 0644, %w(my.rb your.rb his.rb her.rb)
    FileUtils.chmod 0755, '/usr/bin/ruby', verbose: true

Symbolic mode is

    FileUtils.chmod "u=wrx,go=rx", 'somecommand'
    FileUtils.chmod "u=wr,go=rr", %w(my.rb your.rb his.rb her.rb)
    FileUtils.chmod "u=wrx,go=rx", '/usr/bin/ruby', verbose: true

“a”

  is user, group, other mask.

“u”

  is user’s mask.

“g”

  is group’s mask.

“o”

  is other’s mask.

“w”

  is write permission.

“r”

  is read permission.

“x”

  is execute permission.

“X”

  is execute permission for directories only, must be used in conjunction with “+”

“s”

  is uid, gid.

“t”

  is sticky bit.

“+”

  is added to a class given the specified mode.

“-”

  Is removed from a given class given mode.

“=”

  Is the exact nature of the class will be given a specified mode.

    # File lib/fileutils.rb, line 997
    def chmod(mode, list, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message sprintf('chmod %s %s', mode_to_s(mode), list.join(' ')) if verbose
      return if noop
      list.each do |path|
        Entry_.new(path).chmod(fu_mode(mode, path))
      end
    end

chmod_R(mode, list, noop: nil, verbose: nil, force: nil) click to toggle source

Changes permission bits on the named files (in `list`) to the bit pattern represented by `mode`.

    FileUtils.chmod_R 0700, "/tmp/app.#{$$}"
    FileUtils.chmod_R "u=wrx", "/tmp/app.#{$$}"

    # File lib/fileutils.rb, line 1014
    def chmod_R(mode, list, noop: nil, verbose: nil, force: nil)
      list = fu_list(list)
      fu_output_message sprintf('chmod -R%s %s %s',
                                (force ? 'f' : ''),
                                mode_to_s(mode), list.join(' ')) if verbose
      return if noop
      list.each do |root|
        Entry_.new(root).traverse do |ent|
          begin
            ent.chmod(fu_mode(mode, ent.path))
          rescue
            raise unless force
          end
        end
      end
    end

chown(user, group, list, noop: nil, verbose: nil) click to toggle source

Changes owner and group on the named files (in `list`) to the user `user` and the group `group`. `user` and `group` may be an ID (Integer/String) or a name (`String`). If `user` or `group` is nil, this method does not change the attribute.

    FileUtils.chown 'root', 'staff', '/usr/local/bin/ruby'
    FileUtils.chown nil, 'bin', Dir.glob('/usr/bin/*'), verbose: true

    # File lib/fileutils.rb, line 1042
    def chown(user, group, list, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message sprintf('chown %s %s',
                                (group ? "#{user}:#{group}" : user || ':'),
                                list.join(' ')) if verbose
      return if noop
      uid = fu_get_uid(user)
      gid = fu_get_gid(group)
      list.each do |path|
        Entry_.new(path).chown uid, gid
      end
    end

chown_R(user, group, list, noop: nil, verbose: nil, force: nil) click to toggle source

Changes owner and group on the named files (in `list`) to the user `user` and the group `group` recursively. `user` and `group` may be an ID (Integer/String) or a name (`String`). If `user` or `group` is nil, this method does not change the attribute.

    FileUtils.chown_R 'www', 'www', '/var/www/htdocs'
    FileUtils.chown_R 'cvs', 'cvs', '/var/cvs', verbose: true

    # File lib/fileutils.rb, line 1066
    def chown_R(user, group, list, noop: nil, verbose: nil, force: nil)
      list = fu_list(list)
      fu_output_message sprintf('chown -R%s %s %s',
                                (force ? 'f' : ''),
                                (group ? "#{user}:#{group}" : user || ':'),
                                list.join(' ')) if verbose
      return if noop
      uid = fu_get_uid(user)
      gid = fu_get_gid(group)
      list.each do |root|
        Entry_.new(root).traverse do |ent|
          begin
            ent.chown uid, gid
          rescue
            raise unless force
          end
        end
      end
    end

cmp(a, b)
Alias for: compare_file
compare_file(a, b) click to toggle source

Returns true if the contents of a file `a` and a file `b` are identical.

    FileUtils.compare_file('somefile', 'somefile')       #=> true
    FileUtils.compare_file('/dev/null', '/dev/urandom')  #=> false

    # File lib/fileutils.rb, line 809
    def compare_file(a, b)
      return false unless File.size(a) == File.size(b)
      File.open(a, 'rb') {|fa|
        File.open(b, 'rb') {|fb|
          return compare_stream(fa, fb)
        }
      }
    end

Also aliased as: identical?, cmp
compare_stream(a, b) click to toggle source

Returns true if the contents of a stream `a` and `b` are identical.

    # File lib/fileutils.rb, line 827
    def compare_stream(a, b)
      bsize = fu_stream_blksize(a, b)

      sa = String.new(capacity: bsize)
      sb = String.new(capacity: bsize)

      begin
        a.read(bsize, sa)
        b.read(bsize, sb)
        return true if sa.empty? && sb.empty?
      end while sa == sb
      false
    end

copy(src, dest, preserve: nil, noop: nil, verbose: nil)
Alias for: cp
copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false) click to toggle source

Copies a file system entry `src` to `dest`. If `src` is a directory, this method copies its contents recursively. This method preserves file types, c.f. symlink, directory… (FIFO, device files and etc. are not supported yet)

Both of `src` and `dest` must be a path name. `src` must exist, `dest` must not exist.

If `preserve` is true, this method preserves owner, group, and modified time. Permissions are copied regardless `preserve`.

If `dereference_root` is true, this method dereference tree root.

If `remove_destination` is true, this method removes each destination file before copy.

    # File lib/fileutils.rb, line 482
    def copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
      if dereference_root
        src = File.realpath(src)
      end

      Entry_.new(src, nil, false).wrap_traverse(proc do |ent|
        destent = Entry_.new(dest, ent.rel, false)
        File.unlink destent.path if remove_destination && (File.file?(destent.path) || File.symlink?(destent.path))
        ent.copy destent.path
      end, proc do |ent|
        destent = Entry_.new(dest, ent.rel, false)
        ent.copy_metadata destent.path if preserve
      end)
    end

copy_file(src, dest, preserve = false, dereference = true) click to toggle source

Copies file contents of `src` to `dest`. Both of `src` and `dest` must be a path name.

    # File lib/fileutils.rb, line 502
    def copy_file(src, dest, preserve = false, dereference = true)
      ent = Entry_.new(src, nil, dereference)
      ent.copy_file dest
      ent.copy_metadata dest if preserve
    end

copy_stream(src, dest) click to toggle source

Copies stream `src` to `dest`. `src` must respond to read(n) and `dest` must respond to write(str).

    # File lib/fileutils.rb, line 514
    def copy_stream(src, dest)
      IO.copy_stream(src, dest)
    end

cp(src, dest, preserve: nil, noop: nil, verbose: nil) click to toggle source

Copies a file content `src` to `dest`. If `dest` is a directory, copies `src` to `dest/src`.

If `src` is a list of files, then `dest` must be a directory.

    FileUtils.cp 'eval.c', 'eval.c.org'
    FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6'
    FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6', verbose: true
    FileUtils.cp 'symlink', 'dest'   # copy content, "dest" is not a symlink

    # File lib/fileutils.rb, line 419
    def cp(src, dest, preserve: nil, noop: nil, verbose: nil)
      fu_output_message "cp#{preserve ? ' -p' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest(src, dest) do |s, d|
        copy_file s, d, preserve
      end
    end

Also aliased as: copy
cp_lr(src, dest, noop: nil, verbose: nil, dereference_root: true, remove_destination: false) click to toggle source

Hard link `src` to `dest`. If `src` is a directory, this method links all its contents recursively. If `dest` is a directory, links `src` to `dest/src`.

`src` can be a list of files.

If `dereference_root` is true, this method dereference tree root.

If `remove_destination` is true, this method removes each destination file before copy.

    FileUtils.rm_r site_ruby + '/mylib', force: true
    FileUtils.cp_lr 'lib/', site_ruby + '/mylib'

    # Examples of linking several files to target directory.
    FileUtils.cp_lr %w(mail.rb field.rb debug/), site_ruby + '/tmail'
    FileUtils.cp_lr Dir.glob('*.rb'), '/home/aamine/lib/ruby', noop: true, verbose: true

    # If you want to link all contents of a directory instead of the
    # directory itself, c.f. src/x -> dest/x, src/y -> dest/y,
    # use the following code.
    FileUtils.cp_lr 'src/.', 'dest'  # cp_lr('src', 'dest') makes dest/src, but this doesn't.

    # File lib/fileutils.rb, line 332
    def cp_lr(src, dest, noop: nil, verbose: nil,
              dereference_root: true, remove_destination: false)
      fu_output_message "cp -lr#{remove_destination ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest(src, dest) do |s, d|
        link_entry s, d, dereference_root, remove_destination
      end
    end

cp_r(src, dest, preserve: nil, noop: nil, verbose: nil, dereference_root: true, remove_destination: nil) click to toggle source

Copies `src` to `dest`. If `src` is a directory, this method copies all its contents recursively. If `dest` is a directory, copies `src` to `dest/src`.

`src` can be a list of files.

If `dereference_root` is true, this method dereference tree root.

If `remove_destination` is true, this method removes each destination file before copy.

    # Installing Ruby library "mylib" under the site_ruby
    FileUtils.rm_r site_ruby + '/mylib', force: true
    FileUtils.cp_r 'lib/', site_ruby + '/mylib'

    # Examples of copying several files to target directory.
    FileUtils.cp_r %w(mail.rb field.rb debug/), site_ruby + '/tmail'
    FileUtils.cp_r Dir.glob('*.rb'), '/home/foo/lib/ruby', noop: true, verbose: true

    # If you want to copy all contents of a directory instead of the
    # directory itself, c.f. src/x -> dest/x, src/y -> dest/y,
    # use following code.
    FileUtils.cp_r 'src/.', 'dest'     # cp_r('src', 'dest') makes dest/src,
                                       # but this doesn't.

    # File lib/fileutils.rb, line 456
    def cp_r(src, dest, preserve: nil, noop: nil, verbose: nil,
             dereference_root: true, remove_destination: nil)
      fu_output_message "cp -r#{preserve ? 'p' : ''}#{remove_destination ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest(src, dest) do |s, d|
        copy_entry s, d, preserve, dereference_root, remove_destination
      end
    end

getwd()
Alias for: pwd
identical?(a, b)
Alias for: compare_file
install(src, dest, mode: nil, owner: nil, group: nil, preserve: nil, noop: nil, verbose: nil) click to toggle source

If `src` is not same as `dest`, copies it and changes the permission mode to `mode`. If `dest` is a directory, destination is `dest`/`src`. This method removes destination before copy.

    FileUtils.install 'ruby', '/usr/local/bin/ruby', mode: 0755, verbose: true
    FileUtils.install 'lib.rb', '/usr/local/lib/ruby/site_ruby', verbose: true

    # File lib/fileutils.rb, line 850
    def install(src, dest, mode: nil, owner: nil, group: nil, preserve: nil,
                noop: nil, verbose: nil)
      if verbose
        msg = +"install -c"
        msg << ' -p' if preserve
        msg << ' -m ' << mode_to_s(mode) if mode
        msg << " -o #{owner}" if owner
        msg << " -g #{group}" if group
        msg << ' ' << [src,dest].flatten.join(' ')
        fu_output_message msg
      end
      return if noop
      uid = fu_get_uid(owner)
      gid = fu_get_gid(group)
      fu_each_src_dest(src, dest) do |s, d|
        st = File.stat(s)
        unless File.exist?(d) and compare_file(s, d)
          remove_file d, true
          copy_file s, d
          File.utime st.atime, st.mtime, d if preserve
          File.chmod fu_mode(mode, st), d if mode
          File.chown uid, gid, d if uid or gid
        end
      end
    end

link(src, dest, force: nil, noop: nil, verbose: nil)
Alias for: ln
link_entry(src, dest, dereference_root = false, remove_destination = false) click to toggle source

Hard links a file system entry `src` to `dest`. If `src` is a directory, this method links its contents recursively.

Both of `src` and `dest` must be a path name. `src` must exist, `dest` must not exist.

If `dereference_root` is true, this method dereferences the tree root.

If `remove_destination` is true, this method removes each destination file before copy.

    # File lib/fileutils.rb, line 399
    def link_entry(src, dest, dereference_root = false, remove_destination = false)
      Entry_.new(src, nil, dereference_root).traverse do |ent|
        destent = Entry_.new(dest, ent.rel, false)
        File.unlink destent.path if remove_destination && File.file?(destent.path)
        ent.link destent.path
      end
    end

ln(target, link, force: nil, noop: nil, verbose: nil) click to toggle source
ln(target, dir, force: nil, noop: nil, verbose: nil)
ln(targets, dir, force: nil, noop: nil, verbose: nil)

In the first form, creates a hard link `link` which points to `target`. If `link` already exists, raises Errno::EEXIST. But if the `force` option is set, overwrites `link`.

    FileUtils.ln 'gcc', 'cc', verbose: true
    FileUtils.ln '/usr/bin/emacs21', '/usr/bin/emacs'

In the second form, creates a link `dir/target` pointing to `target`. In the third form, creates several hard links in the directory `dir`, pointing to each item in `targets`. If `dir` is not a directory, raises Errno::ENOTDIR.

    FileUtils.cd '/sbin'
    FileUtils.ln %w(cp mv mkdir), '/bin'   # Now /sbin/cp and /bin/cp are linked.

    # File lib/fileutils.rb, line 296
    def ln(src, dest, force: nil, noop: nil, verbose: nil)
      fu_output_message "ln#{force ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest0(src, dest) do |s,d|
        remove_file d, true if force
        File.link s, d
      end
    end

Also aliased as: link
ln_s(target, link, force: nil, noop: nil, verbose: nil) click to toggle source
ln_s(target, dir, force: nil, noop: nil, verbose: nil)
ln_s(targets, dir, force: nil, noop: nil, verbose: nil)

In the first form, creates a symbolic link `link` which points to `target`. If `link` already exists, raises Errno::EEXIST. But if the `force` option is set, overwrites `link`.

    FileUtils.ln_s '/usr/bin/ruby', '/usr/local/bin/ruby'
    FileUtils.ln_s 'verylongsourcefilename.c', 'c', force: true

In the second form, creates a link `dir/target` pointing to `target`. In the third form, creates several symbolic links in the directory `dir`, pointing to each item in `targets`. If `dir` is not a directory, raises Errno::ENOTDIR.

    FileUtils.ln_s Dir.glob('/bin/*.rb'), '/home/foo/bin'

    # File lib/fileutils.rb, line 362
    def ln_s(src, dest, force: nil, noop: nil, verbose: nil)
      fu_output_message "ln -s#{force ? 'f' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest0(src, dest) do |s,d|
        remove_file d, true if force
        File.symlink s, d
      end
    end

Also aliased as: symlink
ln_sf(*args) click to toggle source

Same as

    FileUtils.ln_s(*args, force: true)

    # File lib/fileutils.rb, line 383
    def ln_sf(src, dest, noop: nil, verbose: nil)
      ln_s src, dest, force: true, noop: noop, verbose: verbose
    end

makedirs(list, mode: nil, noop: nil, verbose: nil)
Alias for: mkdir_p
mkdir(list, mode: nil, noop: nil, verbose: nil) click to toggle source

Creates one or more directories.

    FileUtils.mkdir 'test'
    FileUtils.mkdir %w(tmp data)
    FileUtils.mkdir 'notexist', noop: true  # Does not really create.
    FileUtils.mkdir 'tmp', mode: 0700

    # File lib/fileutils.rb, line 180
    def mkdir(list, mode: nil, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message "mkdir #{mode ? ('-m %03o ' % mode) : ''}#{list.join ' '}" if verbose
      return if noop

      list.each do |dir|
        fu_mkdir dir, mode
      end
    end

mkdir_p(list, mode: nil, noop: nil, verbose: nil) click to toggle source

Creates a directory and all its parent directories. For example,

    FileUtils.mkdir_p '/usr/local/lib/ruby'

causes to make following directories, if they do not exist.

- /usr

- /usr/local

- /usr/local/lib

- /usr/local/lib/ruby

You can pass several directories at a time in a list.

    # File lib/fileutils.rb, line 206
    def mkdir_p(list, mode: nil, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message "mkdir -p #{mode ? ('-m %03o ' % mode) : ''}#{list.join ' '}" if verbose
      return *list if noop

      list.each do |item|
        path = remove_trailing_slash(item)

        stack = []
        until File.directory?(path) || File.dirname(path) == path
          stack.push path
          path = File.dirname(path)
        end
        stack.reverse_each do |dir|
          begin
            fu_mkdir dir, mode
          rescue SystemCallError
            raise unless File.directory?(dir)
          end
        end
      end

      return *list
    end

Also aliased as: mkpath, makedirs
mkpath(list, mode: nil, noop: nil, verbose: nil)
Alias for: mkdir_p
move(src, dest, force: nil, noop: nil, verbose: nil, secure: nil)
Alias for: mv
mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil) click to toggle source

Moves file(s) `src` to `dest`. If `file` and `dest` exist on the different disk partition, the file is copied then the original file is removed.

    FileUtils.mv 'badname.rb', 'goodname.rb'
    FileUtils.mv 'stuff.rb', '/notexist/lib/ruby', force: true  # no error

    FileUtils.mv %w(junk.txt dust.txt), '/home/foo/.trash/'
    FileUtils.mv Dir.glob('test*.rb'), 'test', noop: true, verbose: true

    # File lib/fileutils.rb, line 529
    def mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil)
      fu_output_message "mv#{force ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if verbose
      return if noop
      fu_each_src_dest(src, dest) do |s, d|
        destent = Entry_.new(d, nil, true)
        begin
          if destent.exist?
            if destent.directory?
              raise Errno::EEXIST, d
            end
          end
          begin
            File.rename s, d
          rescue Errno::EXDEV,
                 Errno::EPERM # move from unencrypted to encrypted dir (ext4)
            copy_entry s, d, true
            if secure
              remove_entry_secure s, force
            else
              remove_entry s, force
            end
          end
        rescue SystemCallError
          raise unless force
        end
      end
    end

Also aliased as: move
pwd() click to toggle source

Returns the name of the current directory.

    # File lib/fileutils.rb, line 115
    def pwd
      Dir.pwd
    end

Also aliased as: getwd
remove(list, force: nil, noop: nil, verbose: nil)
Alias for: rm
remove_dir(path, force = false) click to toggle source

Removes a directory `dir` and its contents recursively. This method ignores `StandardError` if `force` is true.

    # File lib/fileutils.rb, line 798
    def remove_dir(path, force = false)
      remove_entry path, force   # FIXME?? check if it is a directory
    end

remove_entry(path, force = false) click to toggle source

This method removes a file system entry `path`. `path` might be a regular file, a directory, or something. If `path` is a directory, remove it recursively.

See also remove_entry_secure.

    # File lib/fileutils.rb, line 770
    def remove_entry(path, force = false)
      Entry_.new(path).postorder_traverse do |ent|
        begin
          ent.remove
        rescue
          raise unless force
        end
      end
    rescue
      raise unless force
    end

remove_entry_secure(path, force = false) click to toggle source

This method removes a file system entry `path`. `path` shall be a regular file, a directory, or something. If `path` is a directory, remove it recursively. This method is required to avoid TOCTTOU (time-of-check-to-time-of-use) local security vulnerability of rm_r. `rm_r` causes security hole when:

- Parent directory is world writable (including /tmp).

- Removing directory tree includes world writable directory.

- The system has symbolic link.

To avoid this security hole, this method applies special preprocess. If `path` is a directory, this method chown(2) and chmod(2) all removing directories. This requires the current process is the owner of the removing whole directory tree, or is 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 set.

WARNING: Only the owner of the removing directory tree, or Unix super user (root) should invoke this method. Otherwise this method does not work.

For details of this security vulnerability, see Perl’s case:

- cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2005-0448

- cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2004-0452

For fileutils.rb, this vulnerability is reported in [ruby-dev:26100].

    # File lib/fileutils.rb, line 677
    def remove_entry_secure(path, force = false)
      unless fu_have_symlink?
        remove_entry path, force
        return
      end
      fullpath = File.expand_path(path)
      st = File.lstat(fullpath)
      unless st.directory?
        File.unlink fullpath
        return
      end
      # is a directory.
      parent_st = File.stat(File.dirname(fullpath))
      unless parent_st.world_writable?
        remove_entry path, force
        return
      end
      unless parent_st.sticky?
        raise ArgumentError, "parent directory is world writable, FileUtils#remove_entry_secure does not work; abort: #{path.inspect} (parent directory mode #{'%o' % parent_st.mode})"
      end

      # freeze tree root
      euid = Process.euid
      dot_file = fullpath + "/."
      begin
        File.open(dot_file) {|f|
          unless fu_stat_identical_entry?(st, f.stat)
            # symlink (TOC-to-TOU attack?)
            File.unlink fullpath
            return
          end
          f.chown euid, -1
          f.chmod 0700
        }
      rescue Errno::EISDIR # JRuby in non-native mode can't open files as dirs
        File.lstat(dot_file).tap {|fstat|
          unless fu_stat_identical_entry?(st, fstat)
            # symlink (TOC-to-TOU attack?)
            File.unlink fullpath
            return
          end
          File.chown euid, -1, dot_file
          File.chmod 0700, dot_file
        }
      end

      unless fu_stat_identical_entry?(st, File.lstat(fullpath))
        # TOC-to-TOU attack?
        File.unlink fullpath
        return
      end

      # ---- tree root is frozen ----
      root = Entry_.new(path)
      root.preorder_traverse do |ent|
        if ent.directory?
          ent.chown euid, -1
          ent.chmod 0700
        end
      end
      root.postorder_traverse do |ent|
        begin
          ent.remove
        rescue
          raise unless force
        end
      end
    rescue
      raise unless force
    end

remove_file(path, force = false) click to toggle source

Removes a file `path`. This method ignores `StandardError` if `force` is true.

    # File lib/fileutils.rb, line 787
    def remove_file(path, force = false)
      Entry_.new(path).remove_file
    rescue
      raise unless force
    end

rm(list, force: nil, noop: nil, verbose: nil) click to toggle source

Remove file(s) specified in `list`. This method cannot remove directories. All StandardErrors are ignored when the :force option is set.

    FileUtils.rm %w( junk.txt dust.txt )
    FileUtils.rm Dir.glob('*.so')
    FileUtils.rm 'NotExistFile', force: true   # never raises exception

    # File lib/fileutils.rb, line 569
    def rm(list, force: nil, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message "rm#{force ? ' -f' : ''} #{list.join ' '}" if verbose
      return if noop

      list.each do |path|
        remove_file path, force
      end
    end

Also aliased as: remove
rm_f(list, noop: nil, verbose: nil) click to toggle source

Equivalent to

    FileUtils.rm(list, force: true)

    # File lib/fileutils.rb, line 588
    def rm_f(list, noop: nil, verbose: nil)
      rm list, force: true, noop: noop, verbose: verbose
    end

Also aliased as: safe_unlink
rm_r(list, force: nil, noop: nil, verbose: nil, secure: nil) click to toggle source

remove files `list`[0] `list`[1]… If `list`[n] is a directory, removes its all contents recursively. This method ignores `StandardError` when :force option is set.

    FileUtils.rm_r Dir.glob('/tmp/*')
    FileUtils.rm_r 'some_dir', force: true

WARNING: This method causes local vulnerability if one of parent directories or removing directory tree are world writable (including /tmp, whose permission is 1777), and the current process has strong privilege such as Unix super user (root), and the system has symbolic link. For secure removing, read the documentation of `remove_entry_secure` carefully, and set :secure option to true. Default is `secure: false`.

NOTE: This method calls `remove_entry_secure` if :secure option is set. See also remove_entry_secure.

    # File lib/fileutils.rb, line 615
    def rm_r(list, force: nil, noop: nil, verbose: nil, secure: nil)
      list = fu_list(list)
      fu_output_message "rm -r#{force ? 'f' : ''} #{list.join ' '}" if verbose
      return if noop
      list.each do |path|
        if secure
          remove_entry_secure path, force
        else
          remove_entry path, force
        end
      end
    end

rm_rf(list, noop: nil, verbose: nil, secure: nil) click to toggle source

Equivalent to

    FileUtils.rm_r(list, force: true)

WARNING: This method causes local vulnerability. Read the documentation of `rm_r` first.

    # File lib/fileutils.rb, line 637
    def rm_rf(list, noop: nil, verbose: nil, secure: nil)
      rm_r list, force: true, noop: noop, verbose: verbose, secure: secure
    end

Also aliased as: rmtree
rmdir(list, parents: nil, noop: nil, verbose: nil) click to toggle source

Removes one or more directories.

    FileUtils.rmdir 'somedir'
    FileUtils.rmdir %w(somedir anydir otherdir)
    # Does not really remove directory; outputs message.
    FileUtils.rmdir 'somedir', verbose: true, noop: true

    # File lib/fileutils.rb, line 256
    def rmdir(list, parents: nil, noop: nil, verbose: nil)
      list = fu_list(list)
      fu_output_message "rmdir #{parents ? '-p ' : ''}#{list.join ' '}" if verbose
      return if noop
      list.each do |dir|
        Dir.rmdir(dir = remove_trailing_slash(dir))
        if parents
          begin
            until (parent = File.dirname(dir)) == '.' or parent == dir
              dir = parent
              Dir.rmdir(dir)
            end
          rescue Errno::ENOTEMPTY, Errno::EEXIST, Errno::ENOENT
          end
        end
      end
    end

rmtree(list, noop: nil, verbose: nil, secure: nil)
Alias for: rm_rf
safe_unlink(list, noop: nil, verbose: nil)
Alias for: rm_f
symlink(src, dest, force: nil, noop: nil, verbose: nil)
Alias for: ln_s
touch(list, noop: nil, verbose: nil, mtime: nil, nocreate: nil) click to toggle source

Updates modification time (mtime) and access time (atime) of file(s) in `list`. Files are created if they don’t exist.

    FileUtils.touch 'timestamp'
    FileUtils.touch Dir.glob('*.c');  system 'make'

    # File lib/fileutils.rb, line 1122
    def touch(list, noop: nil, verbose: nil, mtime: nil, nocreate: nil)
      list = fu_list(list)
      t = mtime
      if verbose
        fu_output_message "touch #{nocreate ? '-c ' : ''}#{t ? t.strftime('-t %Y%m%d%H%M.%S ') : ''}#{list.join ' '}"
      end
      return if noop
      list.each do |path|
        created = nocreate
        begin
          File.utime(t, t, path)
        rescue Errno::ENOENT
          raise if created
          File.open(path, 'a') {
            ;
          }
          created = true
          retry if t
        end
      end
    end

uptodate?(new, old_list) click to toggle source

Returns true if `new` is newer than all `old_list`. Non-existent files are older than any file.

    FileUtils.uptodate?('hello.o', %w(hello.c hello.h)) or \
        system 'make hello.o'

    # File lib/fileutils.rb, line 155
    def uptodate?(new, old_list)
      return false unless File.exist?(new)
      new_time = File.mtime(new)
      old_list.each do |old|
        if File.exist?(old)
          return false unless new_time > File.mtime(old)
        end
      end
      true
    end