module FileUtils

用于文件复制、移动、删除等操作的文件工具方法命名空间。

这里有什么

首先，其他地方有什么。 Module FileUtils

继承自 class Object。
补充 class File（但并未包含或扩展在那里）。

在此，module FileUtils 提供了有用的方法，用于

创建

::mkdir：创建目录。
::mkdir_p、::makedirs、::mkpath：创建目录，必要时也创建父目录。
::link_entry：创建硬链接。
::ln、::link：创建硬链接。
::ln_s、::symlink：创建符号链接。
::ln_sf：创建符号链接，必要时覆盖。
::ln_sr：创建相对于目标的符号链接。

删除

::remove_dir：删除目录及其子目录。
::remove_entry：删除条目，如果条目是目录，则包括其子目录。
::remove_entry_secure：类似于 ::remove_entry，但会安全地删除。
::remove_file：删除文件条目。
::rm、::remove：删除条目。
::rm_f、::safe_unlink：类似于 ::rm，但会强制删除。
::rm_r：删除条目及其子目录。
::rm_rf、::rmtree：类似于 ::rm_r，但会强制删除。
::rmdir：删除目录。

查询

::pwd、::getwd：返回当前工作目录的路径。
::uptodate?：返回给定条目是否比给定的其他条目新。

设置

::cd、::chdir：设置工作目录。
::chmod：设置条目的权限。
::chmod_R：设置条目及其子目录的权限。
::chown：设置条目的所有者和组。
::chown_R：设置条目及其子目录的所有者和组。
::touch：设置条目的修改和访问时间，如果不存在则创建。

比较

::compare_file、::cmp、::identical?：返回两个条目是否相同。
::compare_stream：返回两个流是否相同。

复制

::copy_entry：递归复制条目。
::copy_file：复制条目。
::copy_stream：复制流。
::cp、::copy：复制文件。
::cp_lr：递归创建硬链接。
::cp_r：递归复制文件，保留模式、所有者和组。
::install：递归复制文件，可选地设置模式、所有者和组。

移动

::mv、::move：移动条目。

Options

::collect_method：返回接受给定选项的方法的名称。
::commands：返回接受选项的方法的名称。
::have_option?：返回给定方法是否接受给定选项。
::options：返回所有选项名称。
::options_of：返回给定方法的选项名称。

路径参数

FileUtils 中的一些方法接受路径参数，这些参数被解释为文件系统条目的路径。

如果参数是字符串，则该值就是路径。
如果参数具有方法 :to_path，则通过该方法进行转换。
如果参数具有方法 :to_str，则通过该方法进行转换。

关于示例

此处的一些示例涉及文件条目树。对于这些，我们有时使用 tree 命令行实用程序来显示树，它是一个递归目录列表实用程序，可生成文件和目录的深度缩进列表。

我们使用一个辅助方法来启动命令并控制格式。

def tree(dirpath = '.')
  command = "tree --noreport --charset=ascii #{dirpath}"
  system(command)
end

为了说明

tree('src0')
# => src0
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt

避免 TOCTTOU 漏洞

对于某些递归删除条目的方法，存在一个潜在的漏洞，称为检查时间到使用时间（Time-of-check to time-of-use），或 TOCTTOU，当以下情况存在时：

目标路径处的条目的祖先目录是可被任何人写入的；这些目录包括 /tmp。
目标路径处的目录树包含
- 一个可被任何人写入的子目录。
- 一个符号链接。

为了避免该漏洞，您可以使用此方法删除条目：

FileUtils.remove_entry_secure：如果目标路径指向目录，则递归删除。

还有以下方法可用，每种方法都会调用 FileUtils.remove_entry_secure：

FileUtils.rm_r 带有关键字参数 secure: true。
FileUtils.rm_rf 带有关键字参数 secure: true。

最后，此用于移动条目的方法会在源和目标位于不同文件系统时调用 FileUtils.remove_entry_secure（这意味着“移动”实际上是复制和删除）：

FileUtils.mv 带有关键字参数 secure: true。

Method FileUtils.remove_entry_secure 通过应用特殊的预处理来安全删除。

如果目标路径指向目录，则此方法在删除目录时使用 File#chown 和 File#chmod 方法。
目标目录的所有者应为当前进程或超级用户（root）。

警告：您必须确保所有父目录都不能被其他不受信任的用户移动。例如，父目录不应由不受信任的用户拥有，并且除非设置了 sticky bit，否则不应被所有人写入。

有关此安全漏洞的详细信息，请参阅 Perl 案例：

Constants

VERSION: 版本号。

Public Class Methods

cd (dir, verbose: nil) { |dir| ... }

Source

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

将当前工作目录更改为给定的 dir，它应该可解释为路径。

如果未提供块，则将当前目录更改为 dir 处的目录；返回零。

FileUtils.pwd # => "/rdoc/fileutils"
FileUtils.cd('..')
FileUtils.pwd # => "/rdoc"
FileUtils.cd('fileutils')

如果提供了块，则将当前目录更改为 dir 处的目录，并使用参数 dir 调用该块，然后恢复原始的当前目录；返回块的值。

FileUtils.pwd                                     # => "/rdoc/fileutils"
FileUtils.cd('..') { |arg| [arg, FileUtils.pwd] } # => ["..", "/rdoc"]
FileUtils.pwd                                     # => "/rdoc/fileutils"

关键字参数

verbose: true - 打印等效命令。

FileUtils.cd('..')
FileUtils.cd('fileutils')

输出

cd ..
cd fileutils

Source

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

将文件从 src 复制到 dest，dest 不应是目录。

参数 src 和 dest 应可解释为路径。

示例

FileUtils.touch('src0.txt')
FileUtils.copy_file('src0.txt', 'dest0.txt')
File.file?('dest0.txt') # => true

可选参数

dereference - 如果 src 是符号链接，则跟随该链接（默认为 true）。
preserve - 保留文件时间（默认为 false）。
remove_destination - 在复制文件之前删除 dest（默认为 false）。

相关：复制方法。

copy_stream (src, dest)

Source

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

通过 IO.copy_stream 将 IO 流 src 复制到 IO 流 dest。

Source

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

复制文件。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

如果 src 是文件路径且 dest 不是目录路径，则将 src 复制到 dest。

FileUtils.touch('src0.txt')
File.exist?('dest0.txt') # => false
FileUtils.cp('src0.txt', 'dest0.txt')
File.file?('dest0.txt')  # => true

如果 src 是文件路径且 dest 是目录路径，则将 src 复制到 dest/src。

FileUtils.touch('src1.txt')
FileUtils.mkdir('dest1')
FileUtils.cp('src1.txt', 'dest1')
File.file?('dest1/src1.txt') # => true

如果 src 是文件路径数组且 dest 是目录路径，则从每个 src 复制到 dest。

src_file_paths = ['src2.txt', 'src2.dat']
FileUtils.touch(src_file_paths)
FileUtils.mkdir('dest2')
FileUtils.cp(src_file_paths, 'dest2')
File.file?('dest2/src2.txt') # => true
File.file?('dest2/src2.dat') # => true

关键字参数

preserve: true - 保留文件时间。
noop: true - 不复制文件。

verbose: true - 打印等效命令。

FileUtils.cp('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.cp('src1.txt', 'dest1', noop: true, verbose: true)
FileUtils.cp(src_file_paths, 'dest2', noop: true, verbose: true)

输出

cp src0.txt dest0.txt
cp src1.txt dest1
cp src2.txt src2.dat dest2

如果 src 是目录，则引发异常。

相关：复制方法。

也别名为：copy

cp_lr (src, dest, noop: nil, verbose: nil, dereference_root: true, remove_destination: false)

Source

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

创建硬链接。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

如果 src 是目录路径且 dest 不存在，则创建链接 dest 及其子目录，指向 src 及其子目录。

tree('src0')
# => src0
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt
File.exist?('dest0') # => false
FileUtils.cp_lr('src0', 'dest0')
tree('dest0')
# => dest0
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt

如果 src 和 dest 都是目录路径，则创建链接 dest/src 及其子目录，指向 src 及其子目录。

tree('src1')
# => src1
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt
FileUtils.mkdir('dest1')
FileUtils.cp_lr('src1', 'dest1')
tree('dest1')
# => dest1
#    `-- src1
#        |-- sub0
#        |   |-- src0.txt
#        |   `-- src1.txt
#        `-- sub1
#            |-- src2.txt
#            `-- src3.txt

如果 src 是条目路径数组且 dest 是目录路径，则对于 src 中的每个路径 filepath，在 dest/filepath 创建一个指向该路径的链接。

tree('src2')
# => src2
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt
FileUtils.mkdir('dest2')
FileUtils.cp_lr(['src2/sub0', 'src2/sub1'], 'dest2')
tree('dest2')
# => dest2
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt

关键字参数

dereference_root: false - 如果 src 是符号链接，则不解引用它。
noop: true - 不创建链接。
remove_destination: true - 在创建链接之前删除 dest。

verbose: true - 打印等效命令。

FileUtils.cp_lr('src0', 'dest0', noop: true, verbose: true)
FileUtils.cp_lr('src1', 'dest1', noop: true, verbose: true)
FileUtils.cp_lr(['src2/sub0', 'src2/sub1'], 'dest2', noop: true, verbose: true)

输出

cp -lr src0 dest0
cp -lr src1 dest1
cp -lr src2/sub0 src2/sub1 dest2

如果 dest 是现有文件或目录的路径，并且未给出关键字参数 remove_destination: true，则引发异常。

Source

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

递归复制文件。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

复制的文件保留模式、所有者和组；要更改这些，请使用 FileUtils.install。

如果 src 是文件路径且 dest 不是目录路径，则将 src 复制到 dest。

FileUtils.touch('src0.txt')
File.exist?('dest0.txt') # => false
FileUtils.cp_r('src0.txt', 'dest0.txt')
File.file?('dest0.txt')  # => true

如果 src 是文件路径且 dest 是目录路径，则将 src 复制到 dest/src。

FileUtils.touch('src1.txt')
FileUtils.mkdir('dest1')
FileUtils.cp_r('src1.txt', 'dest1')
File.file?('dest1/src1.txt') # => true

如果 src 是目录路径且 dest 不存在，则递归地将 src 复制到 dest。

tree('src2')
# => src2
#    |-- dir0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- dir1
#    |-- src2.txt
#    `-- src3.txt
FileUtils.exist?('dest2') # => false
FileUtils.cp_r('src2', 'dest2')
tree('dest2')
# => dest2
#    |-- dir0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- dir1
#    |-- src2.txt
#    `-- src3.txt

如果 src 和 dest 是目录路径，则递归地将 src 复制到 dest/src。

tree('src3')
# => src3
#    |-- dir0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- dir1
#    |-- src2.txt
#    `-- src3.txt
FileUtils.mkdir('dest3')
FileUtils.cp_r('src3', 'dest3')
tree('dest3')
# => dest3
#    `-- src3
#      |-- dir0
#      |   |-- src0.txt
#      |   `-- src1.txt
#      `-- dir1
#          |-- src2.txt
#          `-- src3.txt

如果 src 是路径数组且 dest 是目录，则递归地将 src 中的每个路径复制到 dest；src 中的路径可以指向文件和/或目录。

关键字参数

dereference_root: false - 如果 src 是符号链接，则不解引用它。
noop: true - 不复制文件。
preserve: true - 保留文件时间。
remove_destination: true - 在复制文件之前删除 dest。

verbose: true - 打印等效命令。

FileUtils.cp_r('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.cp_r('src1.txt', 'dest1', noop: true, verbose: true)
FileUtils.cp_r('src2', 'dest2', noop: true, verbose: true)
FileUtils.cp_r('src3', 'dest3', noop: true, verbose: true)

输出

cp -r src0.txt dest0.txt
cp -r src1.txt dest1
cp -r src2 dest2
cp -r src3 dest3

如果 src 是目录路径且 dest 是文件路径，则引发异常。

相关：复制方法。

getwd ()

别名：pwd

have_option? (mid, opt)

Source

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

如果方法 mid 接受给定的选项 opt，则返回 true，否则返回 false；参数可以是字符串或符号。

FileUtils.have_option?(:chmod, :noop) # => true
FileUtils.have_option?('chmod', 'secure') # => false

identical? (a, b)

别名：compare_file

install (src, dest, mode: nil, owner: nil, group: nil, preserve: nil, noop: nil, verbose: nil)

Source

# File lib/fileutils.rb, line 1607
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
      if d.end_with?('/')
        mkdir_p d
        copy_file s, d + File.basename(s)
      else
        mkdir_p File.expand_path('..', d)
        copy_file s, d
      end
      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

复制文件条目。请参阅 install(1)。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径；

如果 dest 处的条目不存在，则从 src 复制到 dest。

File.read('src0.txt')    # => "aaa\n"
File.exist?('dest0.txt') # => false
FileUtils.install('src0.txt', 'dest0.txt')
File.read('dest0.txt')   # => "aaa\n"

如果 dest 是文件条目，则从 src 复制到 dest，覆盖。

File.read('src1.txt')  # => "aaa\n"
File.read('dest1.txt') # => "bbb\n"
FileUtils.install('src1.txt', 'dest1.txt')
File.read('dest1.txt') # => "aaa\n"

如果 dest 是目录条目，则从 src 复制到 dest/src，必要时覆盖。

File.read('src2.txt')       # => "aaa\n"
File.read('dest2/src2.txt') # => "bbb\n"
FileUtils.install('src2.txt', 'dest2')
File.read('dest2/src2.txt') # => "aaa\n"

如果 src 是路径数组且 dest 指向目录，则将 src 中的每个路径 path 复制到 dest/path。

File.file?('src3.txt') # => true
File.file?('src3.dat') # => true
FileUtils.mkdir('dest3')
FileUtils.install(['src3.txt', 'src3.dat'], 'dest3')
File.file?('dest3/src3.txt') # => true
File.file?('dest3/src3.dat') # => true

关键字参数

group: group - 如果不为 nil，则更改组，使用 File.chown。
mode: permissions - 更改权限，使用 File.chmod。
noop: true - 不复制条目；返回 nil。
owner: owner - 如果不为 nil，则更改所有者，使用 File.chown。
preserve: true - 使用 File.utime 保留时间戳。

verbose: true - 打印等效命令。

FileUtils.install('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.install('src1.txt', 'dest1.txt', noop: true, verbose: true)
FileUtils.install('src2.txt', 'dest2', noop: true, verbose: true)

输出

install -c src0.txt dest0.txt
install -c src1.txt dest1.txt
install -c src2.txt dest2

别名：ln

link_entry (src, dest, dereference_root = false, remove_destination = false)

Source

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

创建硬链接；返回 nil。

参数 src 和 dest 应可解释为路径。

如果 src 是文件路径且 dest 不存在，则在 dest 创建一个指向 src 的硬链接。

FileUtils.touch('src0.txt')
File.exist?('dest0.txt') # => false
FileUtils.link_entry('src0.txt', 'dest0.txt')
File.file?('dest0.txt')  # => true

如果 src 是目录路径且 dest 不存在，则在 dest 递归地创建指向 src 中路径的硬链接。

FileUtils.mkdir_p(['src1/dir0', 'src1/dir1'])
src_file_paths = [
  'src1/dir0/t0.txt',
  'src1/dir0/t1.txt',
  'src1/dir1/t2.txt',
  'src1/dir1/t3.txt',
  ]
FileUtils.touch(src_file_paths)
File.directory?('dest1')        # => true
FileUtils.link_entry('src1', 'dest1')
File.file?('dest1/dir0/t0.txt') # => true
File.file?('dest1/dir0/t1.txt') # => true
File.file?('dest1/dir1/t2.txt') # => true
File.file?('dest1/dir1/t3.txt') # => true

可选参数

dereference_root - 如果 src 是符号链接，则解引用它（默认为 false）。
remove_destination - 在创建链接之前删除 dest（默认为 false）。

如果 dest 是现有文件或目录的路径，并且未提供可选参数 remove_destination，则引发异常。

相关：FileUtils.ln（选项不同）。

ln (src, dest, force: nil, noop: nil, verbose: nil)

Source

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

创建硬链接。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

当 src 是现有文件的路径且 dest 是不存在的文件的路径时，在 dest 创建一个指向 src 的硬链接；返回零。

Dir.children('tmp0/')                    # => ["t.txt"]
Dir.children('tmp1/')                    # => []
FileUtils.ln('tmp0/t.txt', 'tmp1/t.lnk') # => 0
Dir.children('tmp1/')                    # => ["t.lnk"]

当 src 是现有文件的路径且 dest 是现有目录的路径时，在 dest/src 创建一个指向 src 的硬链接；返回零。

Dir.children('tmp2')               # => ["t.dat"]
Dir.children('tmp3')               # => []
FileUtils.ln('tmp2/t.dat', 'tmp3') # => 0
Dir.children('tmp3')               # => ["t.dat"]

当 src 是现有文件路径数组且 dest 是现有目录的路径时，对于 src 中的每个路径 target，在 dest/target 创建一个指向 target 的硬链接；返回 src。

Dir.children('tmp4/')                               # => []
FileUtils.ln(['tmp0/t.txt', 'tmp2/t.dat'], 'tmp4/') # => ["tmp0/t.txt", "tmp2/t.dat"]
Dir.children('tmp4/')                               # => ["t.dat", "t.txt"]

关键字参数

force: true - 如果 dest 存在，则覆盖它。
noop: true - 不创建链接。

verbose: true - 打印等效命令。

FileUtils.ln('tmp0/t.txt', 'tmp1/t.lnk', verbose: true)
FileUtils.ln('tmp2/t.dat', 'tmp3', verbose: true)
FileUtils.ln(['tmp0/t.txt', 'tmp2/t.dat'], 'tmp4/', verbose: true)

输出

ln tmp0/t.txt tmp1/t.lnk
ln tmp2/t.dat tmp3
ln tmp0/t.txt tmp2/t.dat tmp4/

如果 dest 是现有文件的路径且关键字参数 force 不是 true，则引发异常。

相关：FileUtils.link_entry（选项不同）。

也别名为：link

ln_s (src, dest, force: nil, relative: false, target_directory: true, noop: nil, verbose: nil)

Source

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

创建符号链接。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

如果 src 是现有文件的路径：

当 dest 是不存在的文件的路径时，在 dest 创建一个指向 src 的符号链接。

FileUtils.touch('src0.txt')
File.exist?('dest0.txt')   # => false
FileUtils.ln_s('src0.txt', 'dest0.txt')
File.symlink?('dest0.txt') # => true

当 dest 是现有文件的路径时，当且仅当给定关键字参数 force: true 时，在 dest 创建一个指向 src 的符号链接（否则引发异常）。

FileUtils.touch('src1.txt')
FileUtils.touch('dest1.txt')
FileUtils.ln_s('src1.txt', 'dest1.txt', force: true)
FileTest.symlink?('dest1.txt') # => true

FileUtils.ln_s('src1.txt', 'dest1.txt') # Raises Errno::EEXIST.

如果 dest 是目录的路径，则在 dest/src 创建一个指向 src 的符号链接。

FileUtils.touch('src2.txt')
FileUtils.mkdir('destdir2')
FileUtils.ln_s('src2.txt', 'destdir2')
File.symlink?('destdir2/src2.txt') # => true

如果 src 是现有文件路径数组且 dest 是目录，则对于 src 中的每个子项 child，创建符号链接 dest/child 指向 child。

FileUtils.mkdir('srcdir3')
FileUtils.touch('srcdir3/src0.txt')
FileUtils.touch('srcdir3/src1.txt')
FileUtils.mkdir('destdir3')
FileUtils.ln_s(['srcdir3/src0.txt', 'srcdir3/src1.txt'], 'destdir3')
File.symlink?('destdir3/src0.txt') # => true
File.symlink?('destdir3/src1.txt') # => true

关键字参数

force: true - 如果 dest 存在，则覆盖它。
relative: false - 相对于 dest 创建链接。
noop: true - 不创建链接。

verbose: true - 打印等效命令。

FileUtils.ln_s('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.ln_s('src1.txt', 'destdir1', noop: true, verbose: true)
FileUtils.ln_s('src2.txt', 'dest2.txt', force: true, noop: true, verbose: true)
FileUtils.ln_s(['srcdir3/src0.txt', 'srcdir3/src1.txt'], 'destdir3', noop: true, verbose: true)

输出

ln -s src0.txt dest0.txt
ln -s src1.txt destdir1
ln -sf src2.txt dest2.txt
ln -s srcdir3/src0.txt srcdir3/src1.txt destdir3

相关：删除方法。

remove_entry (path, force = false)

Source

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

删除由 path 指定的条目，它应该是一个普通文件、符号链接或目录的条目。

参数 path 应可解释为路径。

可选参数 force 指定是否忽略 StandardError 及其子类的异常。

相关：FileUtils.remove_entry_secure。

remove_entry_secure (path, force = false)

Source

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

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

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

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

安全地删除由 path 指定的条目，它应该是一个普通文件、符号链接或目录的条目。

参数 path 应可解释为路径。

避免了在某些情况下可能存在的本地漏洞；请参阅避免 TOCTTOU 漏洞。

可选参数 force 指定是否忽略 StandardError 及其子类的异常。

相关：删除方法。

remove_file (path, force = false)

Source

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

删除由 path 指定的文件条目，该条目应为常规文件或符号链接。

参数 path 应可解释为路径。

可选参数 force 指定是否忽略 StandardError 及其子类的异常。

相关：删除方法。

rm (list, force: nil, noop: nil, verbose: nil)

Source

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

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

删除给定 list 中的条目（单个路径或路径数组），如果 list 是数组则返回 list，否则返回 [list]。

参数 list 或其元素应可解释为路径。

如果不带关键字参数，则删除 list 中提供的路径下的文件。

FileUtils.touch(['src0.txt', 'src0.dat'])
FileUtils.rm(['src0.dat', 'src0.txt']) # => ["src0.dat", "src0.txt"]

关键字参数

force: true - 忽略由 StandardError 及其后代引发的异常。
noop: true - 不删除文件；返回 nil。

verbose: true - 打印等效命令。

FileUtils.rm(['src0.dat', 'src0.txt'], noop: true, verbose: true)

输出

rm src0.dat src0.txt

相关：删除方法。

也别名为：remove

rm_f (list, noop: nil, verbose: nil)

Source

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

等同于

FileUtils.rm(list, force: true, **kwargs)

参数 list（单个路径或路径数组）应可解释为路径。

请参阅 FileUtils.rm 以了解关键字参数。

相关：删除方法。

也别名为：safe_unlink

rm_r (list, force: nil, noop: nil, verbose: nil, secure: nil)

Source

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

删除给定 list 中的条目（单个路径或路径数组）；如果 list 是数组则返回 list，否则返回 [list]。

参数 list 或其元素应可解释为路径。

如果未调用关键字参数 secure: true，则可能导致本地漏洞；请参阅避免 TOCTTOU 漏洞。

对于每个文件路径，删除该路径下的文件。

FileUtils.touch(['src0.txt', 'src0.dat'])
FileUtils.rm_r(['src0.dat', 'src0.txt'])
File.exist?('src0.txt') # => false
File.exist?('src0.dat') # => false

tree('src1')
# => src1
#    |-- dir0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- dir1
#        |-- src2.txt
#        `-- src3.txt
FileUtils.rm_r('src1')
File.exist?('src1') # => false

关键字参数

force: true - 忽略由 StandardError 及其后代引发的异常。
noop: true - 不删除条目；返回 nil。
secure: true - 安全地删除 src；有关详细信息，请参阅 FileUtils.remove_entry_secure。

verbose: true - 打印等效命令。

FileUtils.rm_r(['src0.dat', 'src0.txt'], noop: true, verbose: true)
FileUtils.rm_r('src1', noop: true, verbose: true)

输出

rm -r src0.dat src0.txt
rm -r src1

Source

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

等同于

FileUtils.rm_r(list, force: true, **kwargs)

参数 list 或其元素应可解释为路径。

如果未调用关键字参数 secure: true，则可能导致本地漏洞；请参阅避免 TOCTTOU 漏洞。

请参阅 FileUtils.rm_r 以了解关键字参数。

相关：删除方法。

也别名为：rmtree

rmdir (list, parents: nil, noop: nil, verbose: nil)

Source

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

删除给定 list 中的目录（单个路径或路径数组）；如果 list 是数组则返回 list，否则返回 [list]。

参数 list 或其元素应可解释为路径。

如果不带关键字参数，则通过调用：Dir.rmdir(path) 来删除 list 中每个 path 下的目录；请参阅 Dir.rmdir。

FileUtils.rmdir(%w[tmp0/tmp1 tmp2/tmp3]) # => ["tmp0/tmp1", "tmp2/tmp3"]
FileUtils.rmdir('tmp4/tmp5')             # => ["tmp4/tmp5"]

关键字参数

parents: true - 如果祖先目录为空，则删除连续的祖先目录。
noop: true - 不删除目录。

verbose: true - 打印等效命令。

FileUtils.rmdir(%w[tmp0/tmp1 tmp2/tmp3], parents: true, verbose: true)
FileUtils.rmdir('tmp4/tmp5', parents: true, verbose: true)

输出

rmdir -p tmp0/tmp1 tmp2/tmp3
rmdir -p tmp4/tmp5

如果目录不存在或因任何原因无法删除目录，则引发异常。

别名为：rm_rf

safe_unlink (list, noop: nil, verbose: nil)

别名为：rm_f

symlink (src, dest, force: nil, relative: false, target_directory: true, noop: nil, verbose: nil)

别名为：ln_s

touch (list, noop: nil, verbose: nil, mtime: nil, nocreate: nil)

Source

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

更新 list（单个路径或路径数组）中条目的修改时间 (mtime) 和访问时间 (atime)；如果 list 是数组则返回 list，否则返回 [list]。

默认情况下，为不存在条目的路径创建一个空文件；使用关键字参数 nocreate 来改为引发异常。

参数 list 或其元素应可解释为路径。

示例

# Single path.
f = File.new('src0.txt') # Existing file.
f.atime # => 2022-06-10 11:11:21.200277 -0700
f.mtime # => 2022-06-10 11:11:21.200277 -0700
FileUtils.touch('src0.txt')
f = File.new('src0.txt')
f.atime # => 2022-06-11 08:28:09.8185343 -0700
f.mtime # => 2022-06-11 08:28:09.8185343 -0700

# Array of paths.
FileUtils.touch(['src0.txt', 'src0.dat'])

关键字参数

mtime: time - 将条目的 mtime 设置为给定时间，而不是当前时间。
nocreate: true - 如果条目不存在，则引发异常。
noop: true - 不 touch 条目；返回 nil。

verbose: true - 打印等效命令。

FileUtils.touch('src0.txt', noop: true, verbose: true)
FileUtils.touch(['src0.txt', 'src0.dat'], noop: true, verbose: true)
FileUtils.touch(path, noop: true, verbose: true)

输出

touch src0.txt
touch src0.txt src0.dat
touch src0.txt

私有实例方法

cd (dir, verbose: nil) { |dir| ... }

Source

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

将当前工作目录更改为给定的 dir，它应该可解释为路径。

如果未提供块，则将当前目录更改为 dir 处的目录；返回零。

FileUtils.pwd # => "/rdoc/fileutils"
FileUtils.cd('..')
FileUtils.pwd # => "/rdoc"
FileUtils.cd('fileutils')

如果提供了块，则将当前目录更改为 dir 处的目录，并使用参数 dir 调用该块，然后恢复原始的当前目录；返回块的值。

FileUtils.pwd                                     # => "/rdoc/fileutils"
FileUtils.cd('..') { |arg| [arg, FileUtils.pwd] } # => ["..", "/rdoc"]
FileUtils.pwd                                     # => "/rdoc/fileutils"

关键字参数

verbose: true - 打印等效命令。

FileUtils.cd('..')
FileUtils.cd('fileutils')

输出

cd ..
cd fileutils

Source

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

将文件从 src 复制到 dest，dest 不应是目录。

参数 src 和 dest 应可解释为路径。

示例

FileUtils.touch('src0.txt')
FileUtils.copy_file('src0.txt', 'dest0.txt')
File.file?('dest0.txt') # => true

可选参数

dereference - 如果 src 是符号链接，则跟随该链接（默认为 true）。
preserve - 保留文件时间（默认为 false）。
remove_destination - 在复制文件之前删除 dest（默认为 false）。

相关：复制方法。

copy_stream (src, dest)

Source

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

通过 IO.copy_stream 将 IO 流 src 复制到 IO 流 dest。

Source

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

复制文件。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

如果 src 是文件路径且 dest 不是目录路径，则将 src 复制到 dest。

FileUtils.touch('src0.txt')
File.exist?('dest0.txt') # => false
FileUtils.cp('src0.txt', 'dest0.txt')
File.file?('dest0.txt')  # => true

如果 src 是文件路径且 dest 是目录路径，则将 src 复制到 dest/src。

FileUtils.touch('src1.txt')
FileUtils.mkdir('dest1')
FileUtils.cp('src1.txt', 'dest1')
File.file?('dest1/src1.txt') # => true

如果 src 是文件路径数组且 dest 是目录路径，则从每个 src 复制到 dest。

src_file_paths = ['src2.txt', 'src2.dat']
FileUtils.touch(src_file_paths)
FileUtils.mkdir('dest2')
FileUtils.cp(src_file_paths, 'dest2')
File.file?('dest2/src2.txt') # => true
File.file?('dest2/src2.dat') # => true

关键字参数

preserve: true - 保留文件时间。
noop: true - 不复制文件。

verbose: true - 打印等效命令。

FileUtils.cp('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.cp('src1.txt', 'dest1', noop: true, verbose: true)
FileUtils.cp(src_file_paths, 'dest2', noop: true, verbose: true)

输出

cp src0.txt dest0.txt
cp src1.txt dest1
cp src2.txt src2.dat dest2

如果 src 是目录，则引发异常。

相关：复制方法。

也别名为：copy

cp_lr (src, dest, noop: nil, verbose: nil, dereference_root: true, remove_destination: false)

Source

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

创建硬链接。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

如果 src 是目录路径且 dest 不存在，则创建链接 dest 及其子目录，指向 src 及其子目录。

tree('src0')
# => src0
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt
File.exist?('dest0') # => false
FileUtils.cp_lr('src0', 'dest0')
tree('dest0')
# => dest0
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt

如果 src 和 dest 都是目录路径，则创建链接 dest/src 及其子目录，指向 src 及其子目录。

tree('src1')
# => src1
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt
FileUtils.mkdir('dest1')
FileUtils.cp_lr('src1', 'dest1')
tree('dest1')
# => dest1
#    `-- src1
#        |-- sub0
#        |   |-- src0.txt
#        |   `-- src1.txt
#        `-- sub1
#            |-- src2.txt
#            `-- src3.txt

如果 src 是条目路径数组且 dest 是目录路径，则对于 src 中的每个路径 filepath，在 dest/filepath 创建一个指向该路径的链接。

tree('src2')
# => src2
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt
FileUtils.mkdir('dest2')
FileUtils.cp_lr(['src2/sub0', 'src2/sub1'], 'dest2')
tree('dest2')
# => dest2
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt

关键字参数

dereference_root: false - 如果 src 是符号链接，则不解引用它。
noop: true - 不创建链接。
remove_destination: true - 在创建链接之前删除 dest。

verbose: true - 打印等效命令。

FileUtils.cp_lr('src0', 'dest0', noop: true, verbose: true)
FileUtils.cp_lr('src1', 'dest1', noop: true, verbose: true)
FileUtils.cp_lr(['src2/sub0', 'src2/sub1'], 'dest2', noop: true, verbose: true)

输出

cp -lr src0 dest0
cp -lr src1 dest1
cp -lr src2/sub0 src2/sub1 dest2

如果 dest 是现有文件或目录的路径，并且未给出关键字参数 remove_destination: true，则引发异常。

Source

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

递归复制文件。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

复制的文件保留模式、所有者和组；要更改这些，请使用 FileUtils.install。

如果 src 是文件路径且 dest 不是目录路径，则将 src 复制到 dest。

FileUtils.touch('src0.txt')
File.exist?('dest0.txt') # => false
FileUtils.cp_r('src0.txt', 'dest0.txt')
File.file?('dest0.txt')  # => true

如果 src 是文件路径且 dest 是目录路径，则将 src 复制到 dest/src。

FileUtils.touch('src1.txt')
FileUtils.mkdir('dest1')
FileUtils.cp_r('src1.txt', 'dest1')
File.file?('dest1/src1.txt') # => true

如果 src 是目录路径且 dest 不存在，则递归地将 src 复制到 dest。

tree('src2')
# => src2
#    |-- dir0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- dir1
#    |-- src2.txt
#    `-- src3.txt
FileUtils.exist?('dest2') # => false
FileUtils.cp_r('src2', 'dest2')
tree('dest2')
# => dest2
#    |-- dir0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- dir1
#    |-- src2.txt
#    `-- src3.txt

如果 src 和 dest 是目录路径，则递归地将 src 复制到 dest/src。

tree('src3')
# => src3
#    |-- dir0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- dir1
#    |-- src2.txt
#    `-- src3.txt
FileUtils.mkdir('dest3')
FileUtils.cp_r('src3', 'dest3')
tree('dest3')
# => dest3
#    `-- src3
#      |-- dir0
#      |   |-- src0.txt
#      |   `-- src1.txt
#      `-- dir1
#          |-- src2.txt
#          `-- src3.txt

如果 src 是路径数组且 dest 是目录，则递归地将 src 中的每个路径复制到 dest；src 中的路径可以指向文件和/或目录。

关键字参数

dereference_root: false - 如果 src 是符号链接，则不解引用它。
noop: true - 不复制文件。
preserve: true - 保留文件时间。
remove_destination: true - 在复制文件之前删除 dest。

verbose: true - 打印等效命令。

FileUtils.cp_r('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.cp_r('src1.txt', 'dest1', noop: true, verbose: true)
FileUtils.cp_r('src2', 'dest2', noop: true, verbose: true)
FileUtils.cp_r('src3', 'dest3', noop: true, verbose: true)

输出

cp -r src0.txt dest0.txt
cp -r src1.txt dest1
cp -r src2 dest2
cp -r src3 dest3

如果 src 是目录路径且 dest 是文件路径，则引发异常。

相关：复制方法。

getwd ()

别名：pwd

identical? (a, b)

别名：compare_file

install (src, dest, mode: nil, owner: nil, group: nil, preserve: nil, noop: nil, verbose: nil)

Source

# File lib/fileutils.rb, line 1607
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
      if d.end_with?('/')
        mkdir_p d
        copy_file s, d + File.basename(s)
      else
        mkdir_p File.expand_path('..', d)
        copy_file s, d
      end
      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

复制文件条目。请参阅 install(1)。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径；

如果 dest 处的条目不存在，则从 src 复制到 dest。

File.read('src0.txt')    # => "aaa\n"
File.exist?('dest0.txt') # => false
FileUtils.install('src0.txt', 'dest0.txt')
File.read('dest0.txt')   # => "aaa\n"

如果 dest 是文件条目，则从 src 复制到 dest，覆盖。

File.read('src1.txt')  # => "aaa\n"
File.read('dest1.txt') # => "bbb\n"
FileUtils.install('src1.txt', 'dest1.txt')
File.read('dest1.txt') # => "aaa\n"

如果 dest 是目录条目，则从 src 复制到 dest/src，必要时覆盖。

File.read('src2.txt')       # => "aaa\n"
File.read('dest2/src2.txt') # => "bbb\n"
FileUtils.install('src2.txt', 'dest2')
File.read('dest2/src2.txt') # => "aaa\n"

如果 src 是路径数组且 dest 指向目录，则将 src 中的每个路径 path 复制到 dest/path。

File.file?('src3.txt') # => true
File.file?('src3.dat') # => true
FileUtils.mkdir('dest3')
FileUtils.install(['src3.txt', 'src3.dat'], 'dest3')
File.file?('dest3/src3.txt') # => true
File.file?('dest3/src3.dat') # => true

关键字参数

group: group - 如果不为 nil，则更改组，使用 File.chown。
mode: permissions - 更改权限，使用 File.chmod。
noop: true - 不复制条目；返回 nil。
owner: owner - 如果不为 nil，则更改所有者，使用 File.chown。
preserve: true - 使用 File.utime 保留时间戳。

verbose: true - 打印等效命令。

FileUtils.install('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.install('src1.txt', 'dest1.txt', noop: true, verbose: true)
FileUtils.install('src2.txt', 'dest2', noop: true, verbose: true)

输出

install -c src0.txt dest0.txt
install -c src1.txt dest1.txt
install -c src2.txt dest2

别名：ln

link_entry (src, dest, dereference_root = false, remove_destination = false)

Source

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

创建硬链接；返回 nil。

参数 src 和 dest 应可解释为路径。

如果 src 是文件路径且 dest 不存在，则在 dest 创建一个指向 src 的硬链接。

FileUtils.touch('src0.txt')
File.exist?('dest0.txt') # => false
FileUtils.link_entry('src0.txt', 'dest0.txt')
File.file?('dest0.txt')  # => true

如果 src 是目录路径且 dest 不存在，则在 dest 递归地创建指向 src 中路径的硬链接。

FileUtils.mkdir_p(['src1/dir0', 'src1/dir1'])
src_file_paths = [
  'src1/dir0/t0.txt',
  'src1/dir0/t1.txt',
  'src1/dir1/t2.txt',
  'src1/dir1/t3.txt',
  ]
FileUtils.touch(src_file_paths)
File.directory?('dest1')        # => true
FileUtils.link_entry('src1', 'dest1')
File.file?('dest1/dir0/t0.txt') # => true
File.file?('dest1/dir0/t1.txt') # => true
File.file?('dest1/dir1/t2.txt') # => true
File.file?('dest1/dir1/t3.txt') # => true

可选参数

dereference_root - 如果 src 是符号链接，则解引用它（默认为 false）。
remove_destination - 在创建链接之前删除 dest（默认为 false）。

如果 dest 是现有文件或目录的路径，并且未提供可选参数 remove_destination，则引发异常。

相关：FileUtils.ln（选项不同）。

ln (src, dest, force: nil, noop: nil, verbose: nil)

Source

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

创建硬链接。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

当 src 是现有文件的路径且 dest 是不存在的文件的路径时，在 dest 创建一个指向 src 的硬链接；返回零。

Dir.children('tmp0/')                    # => ["t.txt"]
Dir.children('tmp1/')                    # => []
FileUtils.ln('tmp0/t.txt', 'tmp1/t.lnk') # => 0
Dir.children('tmp1/')                    # => ["t.lnk"]

当 src 是现有文件的路径且 dest 是现有目录的路径时，在 dest/src 创建一个指向 src 的硬链接；返回零。

Dir.children('tmp2')               # => ["t.dat"]
Dir.children('tmp3')               # => []
FileUtils.ln('tmp2/t.dat', 'tmp3') # => 0
Dir.children('tmp3')               # => ["t.dat"]

当 src 是现有文件路径数组且 dest 是现有目录的路径时，对于 src 中的每个路径 target，在 dest/target 创建一个指向 target 的硬链接；返回 src。

Dir.children('tmp4/')                               # => []
FileUtils.ln(['tmp0/t.txt', 'tmp2/t.dat'], 'tmp4/') # => ["tmp0/t.txt", "tmp2/t.dat"]
Dir.children('tmp4/')                               # => ["t.dat", "t.txt"]

关键字参数

force: true - 如果 dest 存在，则覆盖它。
noop: true - 不创建链接。

verbose: true - 打印等效命令。

FileUtils.ln('tmp0/t.txt', 'tmp1/t.lnk', verbose: true)
FileUtils.ln('tmp2/t.dat', 'tmp3', verbose: true)
FileUtils.ln(['tmp0/t.txt', 'tmp2/t.dat'], 'tmp4/', verbose: true)

输出

ln tmp0/t.txt tmp1/t.lnk
ln tmp2/t.dat tmp3
ln tmp0/t.txt tmp2/t.dat tmp4/

如果 dest 是现有文件的路径且关键字参数 force 不是 true，则引发异常。

相关：FileUtils.link_entry（选项不同）。

也别名为：link

ln_s (src, dest, force: nil, relative: false, target_directory: true, noop: nil, verbose: nil)

Source

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

创建符号链接。

参数 src（单个路径或路径数组）和 dest（单个路径）应可解释为路径。

如果 src 是现有文件的路径：

当 dest 是不存在的文件的路径时，在 dest 创建一个指向 src 的符号链接。

FileUtils.touch('src0.txt')
File.exist?('dest0.txt')   # => false
FileUtils.ln_s('src0.txt', 'dest0.txt')
File.symlink?('dest0.txt') # => true

当 dest 是现有文件的路径时，当且仅当给定关键字参数 force: true 时，在 dest 创建一个指向 src 的符号链接（否则引发异常）。

FileUtils.touch('src1.txt')
FileUtils.touch('dest1.txt')
FileUtils.ln_s('src1.txt', 'dest1.txt', force: true)
FileTest.symlink?('dest1.txt') # => true

FileUtils.ln_s('src1.txt', 'dest1.txt') # Raises Errno::EEXIST.

如果 dest 是目录的路径，则在 dest/src 创建一个指向 src 的符号链接。

FileUtils.touch('src2.txt')
FileUtils.mkdir('destdir2')
FileUtils.ln_s('src2.txt', 'destdir2')
File.symlink?('destdir2/src2.txt') # => true

如果 src 是现有文件路径数组且 dest 是目录，则对于 src 中的每个子项 child，创建符号链接 dest/child 指向 child。

FileUtils.mkdir('srcdir3')
FileUtils.touch('srcdir3/src0.txt')
FileUtils.touch('srcdir3/src1.txt')
FileUtils.mkdir('destdir3')
FileUtils.ln_s(['srcdir3/src0.txt', 'srcdir3/src1.txt'], 'destdir3')
File.symlink?('destdir3/src0.txt') # => true
File.symlink?('destdir3/src1.txt') # => true

关键字参数

force: true - 如果 dest 存在，则覆盖它。
relative: false - 相对于 dest 创建链接。
noop: true - 不创建链接。

verbose: true - 打印等效命令。

FileUtils.ln_s('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.ln_s('src1.txt', 'destdir1', noop: true, verbose: true)
FileUtils.ln_s('src2.txt', 'dest2.txt', force: true, noop: true, verbose: true)
FileUtils.ln_s(['srcdir3/src0.txt', 'srcdir3/src1.txt'], 'destdir3', noop: true, verbose: true)

输出

ln -s src0.txt dest0.txt
ln -s src1.txt destdir1
ln -sf src2.txt dest2.txt
ln -s srcdir3/src0.txt srcdir3/src1.txt destdir3

相关：删除方法。

remove_entry (path, force = false)

Source

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

删除由 path 指定的条目，它应该是一个普通文件、符号链接或目录的条目。

参数 path 应可解释为路径。

可选参数 force 指定是否忽略 StandardError 及其子类的异常。

相关：FileUtils.remove_entry_secure。

remove_entry_secure (path, force = false)

Source

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

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

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

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

安全地删除由 path 指定的条目，它应该是一个普通文件、符号链接或目录的条目。

参数 path 应可解释为路径。

避免了在某些情况下可能存在的本地漏洞；请参阅避免 TOCTTOU 漏洞。

可选参数 force 指定是否忽略 StandardError 及其子类的异常。

相关：删除方法。

remove_file (path, force = false)

Source

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

删除由 path 指定的文件条目，该条目应为常规文件或符号链接。

参数 path 应可解释为路径。

可选参数 force 指定是否忽略 StandardError 及其子类的异常。

相关：删除方法。

rm (list, force: nil, noop: nil, verbose: nil)

Source

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

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

删除给定 list 中的条目（单个路径或路径数组），如果 list 是数组则返回 list，否则返回 [list]。

参数 list 或其元素应可解释为路径。

如果不带关键字参数，则删除 list 中提供的路径下的文件。

FileUtils.touch(['src0.txt', 'src0.dat'])
FileUtils.rm(['src0.dat', 'src0.txt']) # => ["src0.dat", "src0.txt"]

关键字参数

force: true - 忽略由 StandardError 及其后代引发的异常。
noop: true - 不删除文件；返回 nil。

verbose: true - 打印等效命令。

FileUtils.rm(['src0.dat', 'src0.txt'], noop: true, verbose: true)

输出

rm src0.dat src0.txt

相关：删除方法。

也别名为：remove

rm_f (list, noop: nil, verbose: nil)

Source

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

等同于

FileUtils.rm(list, force: true, **kwargs)

参数 list（单个路径或路径数组）应可解释为路径。

请参阅 FileUtils.rm 以了解关键字参数。

相关：删除方法。

也别名为：safe_unlink

rm_r (list, force: nil, noop: nil, verbose: nil, secure: nil)

Source

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

删除给定 list 中的条目（单个路径或路径数组）；如果 list 是数组则返回 list，否则返回 [list]。

参数 list 或其元素应可解释为路径。

如果未调用关键字参数 secure: true，则可能导致本地漏洞；请参阅避免 TOCTTOU 漏洞。

对于每个文件路径，删除该路径下的文件。

FileUtils.touch(['src0.txt', 'src0.dat'])
FileUtils.rm_r(['src0.dat', 'src0.txt'])
File.exist?('src0.txt') # => false
File.exist?('src0.dat') # => false

tree('src1')
# => src1
#    |-- dir0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- dir1
#        |-- src2.txt
#        `-- src3.txt
FileUtils.rm_r('src1')
File.exist?('src1') # => false

关键字参数

force: true - 忽略由 StandardError 及其后代引发的异常。
noop: true - 不删除条目；返回 nil。
secure: true - 安全地删除 src；有关详细信息，请参阅 FileUtils.remove_entry_secure。

verbose: true - 打印等效命令。

FileUtils.rm_r(['src0.dat', 'src0.txt'], noop: true, verbose: true)
FileUtils.rm_r('src1', noop: true, verbose: true)

输出

rm -r src0.dat src0.txt
rm -r src1

Source

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

等同于

FileUtils.rm_r(list, force: true, **kwargs)

参数 list 或其元素应可解释为路径。

如果未调用关键字参数 secure: true，则可能导致本地漏洞；请参阅避免 TOCTTOU 漏洞。

请参阅 FileUtils.rm_r 以了解关键字参数。

相关：删除方法。

也别名为：rmtree

rmdir (list, parents: nil, noop: nil, verbose: nil)

Source

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

删除给定 list 中的目录（单个路径或路径数组）；如果 list 是数组则返回 list，否则返回 [list]。

参数 list 或其元素应可解释为路径。

如果不带关键字参数，则通过调用：Dir.rmdir(path) 来删除 list 中每个 path 下的目录；请参阅 Dir.rmdir。

FileUtils.rmdir(%w[tmp0/tmp1 tmp2/tmp3]) # => ["tmp0/tmp1", "tmp2/tmp3"]
FileUtils.rmdir('tmp4/tmp5')             # => ["tmp4/tmp5"]

关键字参数

parents: true - 如果祖先目录为空，则删除连续的祖先目录。
noop: true - 不删除目录。

verbose: true - 打印等效命令。

FileUtils.rmdir(%w[tmp0/tmp1 tmp2/tmp3], parents: true, verbose: true)
FileUtils.rmdir('tmp4/tmp5', parents: true, verbose: true)

输出

rmdir -p tmp0/tmp1 tmp2/tmp3
rmdir -p tmp4/tmp5

如果目录不存在或因任何原因无法删除目录，则引发异常。

别名为：rm_rf

safe_unlink (list, noop: nil, verbose: nil)

别名为：rm_f

symlink (src, dest, force: nil, relative: false, target_directory: true, noop: nil, verbose: nil)

别名为：ln_s

touch (list, noop: nil, verbose: nil, mtime: nil, nocreate: nil)

Source

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

更新 list（单个路径或路径数组）中条目的修改时间 (mtime) 和访问时间 (atime)；如果 list 是数组则返回 list，否则返回 [list]。

默认情况下，为不存在条目的路径创建一个空文件；使用关键字参数 nocreate 来改为引发异常。

参数 list 或其元素应可解释为路径。

示例

# Single path.
f = File.new('src0.txt') # Existing file.
f.atime # => 2022-06-10 11:11:21.200277 -0700
f.mtime # => 2022-06-10 11:11:21.200277 -0700
FileUtils.touch('src0.txt')
f = File.new('src0.txt')
f.atime # => 2022-06-11 08:28:09.8185343 -0700
f.mtime # => 2022-06-11 08:28:09.8185343 -0700

# Array of paths.
FileUtils.touch(['src0.txt', 'src0.dat'])

关键字参数

mtime: time - 将条目的 mtime 设置为给定时间，而不是当前时间。
nocreate: true - 如果条目不存在，则引发异常。
noop: true - 不 touch 条目；返回 nil。

verbose: true - 打印等效命令。

FileUtils.touch('src0.txt', noop: true, verbose: true)
FileUtils.touch(['src0.txt', 'src0.dat'], noop: true, verbose: true)
FileUtils.touch(path, noop: true, verbose: true)

输出

touch src0.txt
touch src0.txt src0.dat
touch src0.txt