# FileUtils (Module)

In: | fileutils.rb

# fileutils.rb

Copyright © 2000-2003 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_file(srcfilename, destfilename)
      copy_stream(srcstream, deststream)
      compare_file(file_a, file_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.

## Methods

cd chdir chmod cmp compare_file compare_stream copy copy_file copy_stream cp cp_r getwd identical? install link ln ln_s ln_sf makedirs mkdir mkdir_p mkpath move mv pwd remove rm rm_f rm_r rm_rf rmdir rmtree safe_unlink symlink touch uptodate?

## Constants

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

## Classes and Modules

Module FileUtils::NoWrite
Module FileUtils::Verbose

## Public Instance methods

pwd()

Options: (none)

Returns the name of the current directory.

[Source]

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

getwd()

Alias for pwd

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

[Source]

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

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'

[Source]

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

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

[Source]

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

[Source]

    # File fileutils.rb, line 166
      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(%</\z>, '') }.each do |path|
          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

makedirs(list, options = {})

Alias for mkdir_p

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

[Source]

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

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.

[Source]

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

link(src, dest, options = {})

Alias for ln

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'

[Source]

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

symlink(src, dest, options = {})

Alias for ln_s

ln_sf(src, dest, options = {})

Options: noop verbose

Same as

      #ln_s(src, dest, :force)

[Source]

    # File fileutils.rb, line 293
      def ln_sf(src, dest, options = {})
        fu_check_options options, :noop, :verbose
        options = options.dup
        options[:force] = true
        ln_s src, dest, options
      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

[Source]

    # File fileutils.rb, line 313
      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|
          fu_preserve_attr(options[:preserve], s, d) {
              copy_file s, d
          }
        end
      end

copy(src, dest, options = {})

Alias for cp

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

[Source]

    # File fileutils.rb, line 344
      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_copy_dir s, d, '.', options[:preserve]
          else
            fu_p_copy s, d, options[:preserve]
          end
        end
      end

copy_file(src, dest)

Copies file `src` to `dest`. Both of `src` and `dest` must be a filename.

[Source]

    # File fileutils.rb, line 404
      def copy_file(src, dest)
        File.open(src,  'rb') {|r|
          File.open(dest, 'wb') {|w|
            copy_stream r, w
          }
        }
      end

copy_stream(src, dest)

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

[Source]

    # File fileutils.rb, line 416
      def copy_stream(src, dest)
        bsize = fu_stream_blksize(src, dest)
        begin
          while true
            dest.syswrite src.sysread(bsize)
          end
        rescue EOFError
        end
      end

mv(src, dest, options = {})

Options: 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', 'lib/ruby', :force => true

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

[Source]

    # File fileutils.rb, line 438
      def mv(src, dest, options = {})
        fu_check_options options, :noop, :verbose
        fu_output_message "mv #{[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)
            File.unlink d
          end

          begin
            File.rename s, d
          rescue
            if File.symlink?(s)
              File.symlink File.readlink(s), dest
              File.unlink s
            else
              st = File.stat(s)
              copy_file s, d
              File.unlink s
              File.utime st.atime, st.mtime, d
              begin
                File.chown st.uid, st.gid, d
              rescue
                # ignore

              end
            end
          end
        end
      end

move(src, dest, options = {})

Alias for mv

rm(list, options = {})

Options: force noop verbose

Remove file(s) specified in `list`. This method cannot remove directories. All errors 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

[Source]

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

remove(list, options = {})

Alias for rm

rm_f(list, options = {})

Options: noop verbose

Same as

      #rm(list, :force)

[Source]

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

safe_unlink(list, options = {})

Alias for rm_f

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          #  :-)

[Source]

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

[Source]

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

rmtree(list, options = {})

Alias for rm_rf

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

[Source]

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

identical?(a, b)

Alias for compare_file

cmp(a, b)

Alias for compare_file

compare_stream(a, b)

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

[Source]

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

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

[Source]

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

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

[Source]

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

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'

[Source]

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

[Validate]