module FileUtils - Documentation for Ruby 2.3.0 (original) (raw)

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.

FileUtils.cd(dir, options) FileUtils.cd(dir, options) {|dir| .... } 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(old, new, options) FileUtils.ln(list, destdir, options) FileUtils.ln_s(old, new, options) FileUtils.ln_s(list, destdir, options) FileUtils.ln_sf(src, dest, 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, mode = <src's>, 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 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 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

Public Class Methods

cd(dir, options = {}) { |dir| ... } click to toggle source

Options: 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

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

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

Also aliased as: chdir

chdir(dir, options = {})

Alias for: cd

chmod(mode, list, options = {}) click to toggle source

Options: noop verbose

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.

def chmod(mode, list, options = {}) fu_check_options options, OPT_TABLE['chmod'] list = fu_list(list) fu_output_message sprintf('chmod %s %s', mode_to_s(mode), list.join(' ')) if options[:verbose] return if options[:noop] list.each do |path| Entry_.new(path).chmod(fu_mode(mode, path)) end end

chmod_R(mode, list, options = {}) click to toggle source

Options: noop verbose force

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.#{$$}"

def chmod_R(mode, list, options = {}) fu_check_options options, OPT_TABLE['chmod_R'] list = fu_list(list) fu_output_message sprintf('chmod -R%s %s %s', (options[:force] ? 'f' : ''), mode_to_s(mode), list.join(' ')) if options[:verbose] return if options[:noop] list.each do |root| Entry_.new(root).traverse do |ent| begin ent.chmod(fu_mode(mode, ent.path)) rescue raise unless options[:force] end end end end

chown(user, group, list, options = {}) click to toggle source

Options: noop verbose

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

def chown(user, group, list, options = {}) fu_check_options options, OPT_TABLE['chown'] list = fu_list(list) fu_output_message sprintf('chown %s %s', (group ? "#{user}:#{group}" : user || ':'), list.join(' ')) if options[:verbose] return if options[: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, options = {}) click to toggle source

Options: noop verbose force

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

def chown_R(user, group, list, options = {}) fu_check_options options, OPT_TABLE['chown_R'] list = fu_list(list) fu_output_message sprintf('chown -R%s %s %s', (options[:force] ? 'f' : ''), (group ? "#{user}:#{group}" : user || ':'), list.join(' ')) if options[:verbose] return if options[: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 options[:force] end end end 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')
FileUtils.compare_file('/bin/cp', '/bin/mv')

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) click to toggle source

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

def compare_stream(a, b) bsize = fu_stream_blksize(a, b) sa = "" sb = "" 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, options = {})

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.

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) 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.

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).

def copy_stream(src, dest) IO.copy_stream(src, dest) end

cp(src, dest, options = {}) click to toggle source

Options: preserve noop verbose

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'

def cp(src, dest, options = {}) fu_check_options options, OPT_TABLE['cp'] 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

Also aliased as: copy

cp_r(src, dest, options = {}) click to toggle source

Options: preserve noop verbose dereference_root remove_destination

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.

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

FileUtils.cp_r %w(mail.rb field.rb debug/), site_ruby + '/tmail' FileUtils.cp_r Dir.glob('*.rb'), '/home/aamine/lib/ruby', :noop => true, :verbose => true

FileUtils.cp_r 'src/.', 'dest'

def cp_r(src, dest, options = {}) fu_check_options options, OPT_TABLE['cp_r'] fu_output_message "cp -r#{options[:preserve] ? 'p' : ''}#{options[:remove_destination] ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose] return if options[:noop] options = options.dup options[:dereference_root] = true unless options.key?(:dereference_root) fu_each_src_dest(src, dest) do |s, d| copy_entry s, d, options[:preserve], options[:dereference_root], options[:remove_destination] end end

install(src, dest, options = {}) click to toggle source

Options: mode preserve 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. 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

def install(src, dest, options = {}) fu_check_options options, OPT_TABLE['install'] 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| 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 options[:preserve] File.chmod options[:mode], d if options[:mode] end end end

link(src, dest, options = {})

Alias for: ln

ln(src, dest, options = {}) click to toggle source

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 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 '/sbin' FileUtils.ln %w(cp mv mkdir), '/bin'

def ln(src, dest, options = {}) fu_check_options options, OPT_TABLE['ln'] 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

Also aliased as: link

ln_s(src, dest, options = {}) click to toggle source

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'

def ln_s(src, dest, options = {}) fu_check_options options, OPT_TABLE['ln_s'] 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 = {}) click to toggle source

Options: noop verbose

Same as

def ln_sf(src, dest, options = {}) fu_check_options options, OPT_TABLE['ln_sf'] options = options.dup options[:force] = true ln_s src, dest, options end

makedirs(list, options = {})

mkdir(list, options = {}) click to toggle source

Options: mode noop verbose

Creates one or more directories.

FileUtils.mkdir 'test' FileUtils.mkdir %w( tmp data ) FileUtils.mkdir 'notexist', :noop => true
FileUtils.mkdir 'tmp', :mode => 0700

def mkdir(list, options = {}) fu_check_options options, OPT_TABLE['mkdir'] list = fu_list(list) fu_output_message "mkdir #{options[:mode] ? ('-m %03o ' % options[:mode]) : ''}#{list.join ' '}" if options[:verbose] return if options[:noop]

list.each do |dir| fu_mkdir dir, options[:mode] end end

mkdir_p(list, options = {}) click to toggle source

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.

def mkdir_p(list, options = {}) fu_check_options options, OPT_TABLE['mkdir_p'] 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]

list.map {|path| remove_trailing_slash(path)}.each do |path|

begin
  fu_mkdir path, options[:mode]
  next
rescue SystemCallError
  next if File.directory?(path)
end

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

end

return *list end

mkpath(list, options = {})

move(src, dest, options = {})

Alias for: mv

mv(src, dest, options = {}) click to toggle source

Options: force noop verbose

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

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

def mv(src, dest, options = {}) fu_check_options options, OPT_TABLE['mv'] 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| 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 options[:secure] remove_entry_secure s, options[:force] else remove_entry s, options[:force] end end rescue SystemCallError raise unless options[:force] end end end

Also aliased as: move

pwd() click to toggle source

Options: (none)

Returns the name of the current directory.

Also aliased as: getwd

remove(list, options = {})

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.

def remove_dir(path, force = false) remove_entry path, force
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)

def FileUtils.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

def FileUtils.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)
p FileUtils.have_option?(:rm, :force)
p FileUtils.have_option?(:rm, :preserve)

def FileUtils.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

def FileUtils.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)

def FileUtils.options_of(mid) OPT_TABLE[mid.to_s].map {|sym| sym.to_s } end

Public Instance Methods

apply_mask(mode, user_mask, op, mode_mask) click to toggle source

def apply_mask(mode, user_mask, op, mode_mask) case op when '=' (mode & ~user_mask) | (user_mask & mode_mask) when '+' mode | (user_mask & mode_mask) when '-' mode & ~(user_mask & mode_mask) end end

remove_trailing_slash(dir) click to toggle source

def remove_trailing_slash(dir) dir == '/' ? dir : dir.chomp(?/) end

Private Instance Methods