module FileUtils

fileutils.rb¶ ↑

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)

The options parameter is a hash of options, taken from the list :force, :noop, :preserve, and :verbose. :noop means that no changes are made. The other three are obvious. Each method documents the options that it honours.

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 any option:

FileUtils.copy_entry(src, dest, preserve = false, dereference = 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

LOW_METHODS
METHODS
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 old working directory after the block execution finished.

FileUtils.cd('/', :verbose => true)   # chdir and report it

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

# File lib/fileutils.rb, line 119
def cd(dir, verbose: nil, &block) # :yield: dir
  fu_output_message "cd #{dir}" if verbose
  Dir.chdir(dir, &block)
  fu_output_message 'cd -' if verbose and block
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 915
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 932
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 960
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 984
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 726
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 744
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 413
def copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
  Entry_.new(src, nil, dereference_root).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 429
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 441
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 354
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_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.

# Installing Ruby library "mylib" under the site_ruby
FileUtils.rm_r site_ruby + '/mylib', :force
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 387
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 765
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

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 284
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 317
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 338
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 161
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 it does 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 187
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.map {|path| remove_trailing_slash(path)}.each do |path|
    # optimize for the most common case
    begin
      fu_mkdir path, mode
      next
    rescue SystemCallError
      next if File.directory?(path)
    end

    stack = []
    until path == stack.last   # dirname("/")=="/", dirname("C:/")=="C:/"
      stack.push path
      path = File.dirname(path)
    end
    stack.pop                 # root directory should exist
    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 456
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
        else
          destent.remove_file if rename_cannot_overwrite_file?
        end
      end
      begin
        File.rename s, d
      rescue Errno::EXDEV
        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 99
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 715
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.

Private Class Methods

collect_method(opt) click to toggle source

Returns an Array of method names which have the option opt.

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

# File lib/fileutils.rb, line 1550
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 method names which have any options.

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

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

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 1531
def self.have_option?(mid, opt)
  li = OPT_TABLE[mid.to_s] or raise ArgumentError, "no such method: #{mid}"
  li.include?(opt)
end

options() click to toggle source

Returns an Array of option names.

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

# File lib/fileutils.rb, line 1520
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 1541
def self.options_of(mid)
  OPT_TABLE[mid.to_s].map {|sym| sym.to_s }
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 old working directory after the block execution finished.

FileUtils.cd('/', :verbose => true)   # chdir and report it

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

# File lib/fileutils.rb, line 119
def cd(dir, verbose: nil, &block) # :yield: dir
  fu_output_message "cd #{dir}" if verbose
  Dir.chdir(dir, &block)
  fu_output_message 'cd -' if verbose and block
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 915
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 932
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

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

# File lib/fileutils.rb, line 960
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

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

# File lib/fileutils.rb, line 984
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 726
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 744
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

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 413
def copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
  Entry_.new(src, nil, dereference_root).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 429
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 441
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 354
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_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.

# Installing Ruby library "mylib" under the site_ruby
FileUtils.rm_r site_ruby + '/mylib', :force
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 387
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 765
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

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'

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

# File lib/fileutils.rb, line 284
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

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

# File lib/fileutils.rb, line 317
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 338
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 161
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 it does 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 187
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.map {|path| remove_trailing_slash(path)}.each do |path|
    # optimize for the most common case
    begin
      fu_mkdir path, mode
      next
    rescue SystemCallError
      next if File.directory?(path)
    end

    stack = []
    until path == stack.last   # dirname("/")=="/", dirname("C:/")=="C:/"
      stack.push path
      path = File.dirname(path)
    end
    stack.pop                 # root directory should exist
    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 456
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
        else
          destent.remove_file if rename_cannot_overwrite_file?
        end
      end
      begin
        File.rename s, d
      rescue Errno::EXDEV
        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 99
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 715
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.