Module

FileUtils

In:

fileutils.rb

Copyright © 2000-2004 Minero Aoki <aamine@loveruby.net>

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

  cd(dir, options)
  cd(dir, options) {|dir| .... }
  pwd()
  mkdir(dir, options)
  mkdir_p(dir, options)
  rmdir(dir, options)
  ln(old, new, options)
  ln(list, destdir, options)
  ln_s(old, new, options)
  ln_s(list, destdir, options)
  ln_sf(src, dest, options)
  cp(src, dest, options)
  cp(list, dir, options)
  cp_r(src, dest, options)
  cp_r(list, dir, options)
  mv(src, dest, options)
  mv(list, dir, options)
  rm(list, options)
  rm_r(list, options)
  rm_rf(list, options)
  install(src, dest, mode = <src's>, options)
  chmod(mode, list, options)
  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 two 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 does not accept any option:

  uptodate?(file, cmp_list)
  copy_entry(src, dest, preserve = false, dereference = false)
  copy_file(src, dest, preserve = false, dereference = true)
  copy_stream(srcstream, deststream)
  compare_file(path_a, path_b)
  compare_stream(stream_a, stream_b)

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.

Classes and Modules

Module FileUtils::DryRun
Module FileUtils::NoWrite
Module FileUtils::Verbose
Class FileUtils::CopyContext_

Constants

OPT_TABLE = { 'cd' => %w( noop verbose ), 'chdir' => %w( noop verbose ), 'chmod' => %w( noop verbose ), 'copy' => %w( noop verbose preserve ), 'cp' => %w( noop verbose preserve ), 'cp_r' => %w( noop verbose preserve ), 'install' => %w( noop verbose preserve mode ), 'link' => %w( noop verbose force ), 'ln' => %w( noop verbose force ), 'ln_s' => %w( noop verbose force ), 'ln_sf' => %w( noop verbose ), 'makedirs' => %w( noop verbose ), 'mkdir' => %w( noop verbose mode ), 'mkdir_p' => %w( noop verbose mode ), 'mkpath' => %w( noop verbose ), 'move' => %w( noop verbose force ), 'mv' => %w( noop verbose force ), 'remove' => %w( noop verbose force ), 'rm' => %w( noop verbose force ), 'rm_f' => %w( noop verbose ), 'rm_r' => %w( noop verbose force ), 'rm_rf' => %w( noop verbose ), 'rmtree' => %w( noop verbose ), 'rmdir' => %w( noop verbose ), 'safe_unlink' => %w( noop verbose ), 'symlink' => %w( noop verbose force ), 'touch' => %w( noop verbose )

Public Instance methods

cd(dir, options = {}) {|dir| ...}

Options: noop verbose

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

# File fileutils.rb, line 102
  def cd(dir, options = {}, &block) # :yield: dir

    fu_check_options options, :noop, :verbose
    fu_output_message "cd #{dir}" if options[:verbose]
    Dir.chdir(dir, &block) unless options[:noop]
    fu_output_message 'cd -' if options[:verbose] and block
  end

chdir(dir, options = {})

Alias for cd

chmod(mode, list, options = {})

Options: noop verbose

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

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

# File fileutils.rb, line 786
  def chmod(mode, list, options = {})
    fu_check_options options, :noop, :verbose
    list = fu_list(list)
    fu_output_message sprintf('chmod %o %s', mode, list.join(' ')) if options[:verbose]
    return if options[:noop]
    File.chmod mode, *list
  end

cmp(a, b)

Alias for compare_file

compare_file(a, b)

Returns true if the contents of a file A and a file B are identical.

  FileUtils.compare_file('somefile', 'somefile')  #=> true
  FileUtils.compare_file('/bin/cp', '/bin/mv')    #=> maybe false

# File fileutils.rb, line 719
  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

compare_stream(a, b)

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

# File fileutils.rb, line 734
  def compare_stream(a, b)
    bsize = fu_stream_blksize(a, b)
    sa = sb = nil
    while sa == sb
      sa = a.read(bsize)
      sb = b.read(bsize)
      unless sa and sb
        if sa.nil? and sb.nil?
          return true
        end
      end
    end
    false
  end

copy(src, dest, options = {})

Alias for cp

copy_entry(src, dest, preserve = false, dereference = false)

Copies a file system entry src to dest. This method preserves file types, c.f. FIFO, device files, directory.…

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 permissions. If dereference is true, this method copies a target of symbolic link instead of a symbolic link itself.

# File fileutils.rb, line 407
  def copy_entry(src, dest, preserve = false, dereference = false)
    CopyContext_.new(preserve, dereference).copy_entry src, dest
  end

copy_file(src, dest, preserve = false, dereference = true)

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

# File fileutils.rb, line 415
  def copy_file(src, dest, preserve = false, dereference = true)
    CopyContext_.new(preserve, dereference).copy_content src, dest
  end

copy_stream(src, dest)

Copies stream src to dest. Both of src and dest must be a IO.

# File fileutils.rb, line 423
  def copy_stream(src, dest)
    fu_copy_stream0 src, dest, fu_stream_blksize(src, dest)
  end

cp(src, dest, options = {})

Options: preserve noop verbose

Copies a file 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

# File fileutils.rb, line 328
  def cp(src, dest, options = {})
    fu_check_options options, :preserve, :noop, :verbose
    fu_output_message "cp#{options[:preserve] ? ' -p' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
    return if options[:noop]

    fu_each_src_dest(src, dest) do |s,d|
      copy_file s, d, options[:preserve]
    end
  end

cp_r(src, dest, options = {})

Options: preserve noop verbose

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/aamine/lib/ruby', :noop, :verbose

  # 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 src/dest,
                                     # but this doesn't.

# File fileutils.rb, line 363
  def cp_r(src, dest, options = {})
    fu_check_options options, :preserve, :noop, :verbose
    fu_output_message "cp -r#{options[:preserve] ? 'p' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
    return if options[:noop]

    fu_each_src_dest(src, dest) do |s,d|
      if File.directory?(s)
        fu_traverse(s) {|rel, deref, st|
          ctx = CopyContext_.new(options[:preserve], deref, st)
          ctx.copy_entry "#{s}/#{rel}", "#{d}/#{rel}"
        }
      else
        copy_file s, d, options[:preserve]
      end
    end
  end

getwd()

Alias for pwd

identical?(a, b)

Alias for compare_file

install(src, dest, options = {})

Options: mode noop verbose

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.

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

# File fileutils.rb, line 759
  def install(src, dest, options = {})
    fu_check_options options, :mode, :preserve, :noop, :verbose
    fu_output_message "install -c#{options[:preserve] && ' -p'}#{options[:mode] ? (' -m 0%o' % options[:mode]) : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
    return if options[:noop]

    fu_each_src_dest(src, dest) do |s,d|
      unless File.exist?(d) and compare_file(s,d)
        remove_file d, true
        st = File.stat(s) if options[:preserve]
        copy_file s, d
        File.utime st.atime, st.mtime, d if options[:preserve]
        File.chmod options[:mode], d if options[:mode]
      end
    end
  end

link(src, dest, options = {})

Alias for ln

ln(src, dest, options = {})

Options: force noop verbose

ln( old, new, options = {} )

Creates a hard link new which points to old. If new already exists and it is a directory, creates a symbolic link +new/old+. If new already exists and it is not a directory, raises Errno::EEXIST. But if :force option is set, overwrite new.

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

ln( list, destdir, options = {} )

Creates several hard links in a directory, with each one pointing to the item in list. If destdir is not a directory, raises Errno::ENOTDIR.

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

# File fileutils.rb, line 254
  def ln(src, dest, options = {})
    fu_check_options options, :force, :noop, :verbose
    fu_output_message "ln#{options[:force] ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
    return if options[:noop]

    fu_each_src_dest0(src, dest) do |s,d|
      remove_file d, true if options[:force]
      File.link s, d
    end
  end

ln_s(src, dest, options = {})

Options: force noop verbose

ln_s( old, new, options = {} )

Creates a symbolic link new which points to old. If new already exists and it is a directory, creates a symbolic link +new/old+. If new already exists and it is not a directory, raises Errno::EEXIST. But if :force option is set, overwrite new.

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

ln_s( list, destdir, options = {} )

Creates several symbolic links in a directory, with each one pointing to the item in list. If destdir is not a directory, raises Errno::ENOTDIR.

If destdir is not a directory, raises Errno::ENOTDIR.

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

# File fileutils.rb, line 289
  def ln_s(src, dest, options = {})
    fu_check_options options, :force, :noop, :verbose
    fu_output_message "ln -s#{options[:force] ? 'f' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
    return if options[:noop]

    fu_each_src_dest0(src, dest) do |s,d|
      remove_file d, true if options[:force]
      File.symlink s, d
    end
  end

ln_sf(src, dest, options = {})

Options: noop verbose

Same as

  #ln_s(src, dest, :force)

# File fileutils.rb, line 308
  def ln_sf(src, dest, options = {})
    fu_check_options options, :noop, :verbose
    options = options.dup
    options[:force] = true
    ln_s src, dest, options
  end

makedirs(list, options = {})

Alias for mkdir_p

mkdir(list, options = {})

Options: mode noop verbose

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 fileutils.rb, line 145
  def mkdir(list, options = {})
    fu_check_options options, :mode, :noop, :verbose
    list = fu_list(list)
    fu_output_message "mkdir #{options[:mode] ? ('-m %03o ' % options[:mode]) : ''}#{list.join ' '}" if options[:verbose]
    return if options[:noop]

    mode = options[:mode] || (0777 & ~File.umask)
    list.each do |dir|
      Dir.mkdir dir.sub(%r</\z>, ''), mode
    end
  end

mkdir_p(list, options = {})

Options: mode noop verbose

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 fileutils.rb, line 173
  def mkdir_p(list, options = {})
    fu_check_options options, :mode, :noop, :verbose
    list = fu_list(list)
    fu_output_message "mkdir -p #{options[:mode] ? ('-m %03o ' % options[:mode]) : ''}#{list.join ' '}" if options[:verbose]
    return *list if options[:noop]

    mode = options[:mode] || (0777 & ~File.umask)
    list.map {|path| path.sub(%r</\z>, '') }.each do |path|
      # optimize for the most common case

      begin
        Dir.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.reverse_each do |path|
        begin
          Dir.mkdir path, mode
        rescue SystemCallError => err
          raise unless File.directory?(path)
        end
      end
    end

    return *list
  end

mkpath(list, options = {})

Alias for mkdir_p

move(src, dest, options = {})

Alias for mv

mv(src, dest, options = {})

Options: force noop verbose

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

  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/aamine/.trash/'
  FileUtils.mv Dir.glob('test*.rb'), 'test', :noop => true, :verbose => true

# File fileutils.rb, line 559
  def mv(src, dest, options = {})
    fu_check_options options, :force, :noop, :verbose
    fu_output_message "mv#{options[:force] ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
    return if options[:noop]

    fu_each_src_dest(src, dest) do |s,d|
      if rename_cannot_overwrite_file? and File.file?(d)
        begin
          File.unlink d
        rescue SystemCallError
          raise unless options[:force]
        end
      end
      begin
        File.rename s, d
      rescue SystemCallError
        begin
          copy_entry s, d, true
          File.unlink s
        rescue SystemCallError
          raise unless options[:force]
        end
      end
    end
  end

Options: (none)

Returns the name of the current directory.

# File fileutils.rb, line 86
  def pwd
    Dir.pwd
  end

remove(list, options = {})

Alias for rm

rm(list, options = {})

Options: force noop verbose

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 fileutils.rb, line 603
  def rm(list, options = {})
    fu_check_options options, :force, :noop, :verbose
    list = fu_list(list)
    fu_output_message "rm#{options[:force] ? ' -f' : ''} #{list.join ' '}" if options[:verbose]
    return if options[:noop]

    list.each do |fname|
      remove_file fname, options[:force]
    end
  end

rm_f(list, options = {})

Options: noop verbose

Same as

  #rm(list, :force)

# File fileutils.rb, line 622
  def rm_f(list, options = {})
    fu_check_options options, :noop, :verbose
    options = options.dup
    options[:force] = true
    rm list, options
  end

rm_r(list, options = {})

Options: force noop verbose

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 '/', :force => true          #  :-)

# File fileutils.rb, line 641
  def rm_r(list, options = {})
    fu_check_options options, :force, :noop, :verbose
    list = fu_list(list)
    fu_output_message "rm -r#{options[:force] ? 'f' : ''} #{list.join ' '}" if options[:verbose]
    return if options[:noop]

    list.each do |fname|
      begin
        st = File.lstat(fname)
      rescue
        next if options[:force]
        raise
      end
      if    st.symlink?   then remove_file fname, options[:force]
      elsif st.directory? then remove_dir fname, options[:force]
      else                     remove_file fname, options[:force]
      end
    end
  end

rm_rf(list, options = {})

Options: noop verbose

Same as

  #rm_r(list, :force => true)

# File fileutils.rb, line 667
  def rm_rf(list, options = {})
    fu_check_options options, :noop, :verbose
    options = options.dup
    options[:force] = true
    rm_r list, options
  end

rmdir(list, options = {})

Options: noop, verbose

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 fileutils.rb, line 220
  def rmdir(list, options = {})
    fu_check_options options, :noop, :verbose
    list = fu_list(list)
    fu_output_message "rmdir #{list.join ' '}" if options[:verbose]
    return if options[:noop]

    list.each do |dir|
      Dir.rmdir dir.sub(%r</\z>, '')
    end
  end

rmtree(list, options = {})

Alias for rm_rf

safe_unlink(list, options = {})

Alias for rm_f

symlink(src, dest, options = {})

Alias for ln_s

touch(list, options = {})

Options: noop verbose

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 fileutils.rb, line 804
  def touch(list, options = {})
    fu_check_options options, :noop, :verbose
    list = fu_list(list)
    fu_output_message "touch #{list.join ' '}" if options[:verbose]
    return if options[:noop]

    t = Time.now
    list.each do |fname|
      begin
        File.utime(t, t, fname)
      rescue Errno::ENOENT
        File.open(fname, 'a') {
          ;
        }
      end
    end
  end

uptodate?(new, old_list, options = nil)

Options: (none)

Returns true if newer 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 fileutils.rb, line 121
  def uptodate?(new, old_list, options = nil)
    raise ArgumentError, 'uptodate? does not accept any option' if options

    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