module FileUtils

要約

基本的なファイル操作を集めたモジュールです。

オプションの説明

引数 options で使用できるオプションの説明です。メソッドごとに使用できるオプションは決まっています。不正なオプションを与えると ArgumentError が発生します。

:noop

真を指定すると実際の処理は行いません。

:preserve

真を指定すると更新時刻と、可能なら所有ユーザ・所有グループもコピーします。

:verbose

真を指定すると詳細を出力します。

:mode

パーミッションを8進数で指定します。

:force

真を指定すると作業中すべての StandardError を無視します。

:nocreate

真を指定するとファイルを作成しません。

:dereference_root

真を指定すると src についてだけシンボリックリンクの指す内容をコピーします。偽の場合はシンボリックリンク自体をコピーします。

:remove_destination

真を指定するとコピーを実行する前にコピー先を削除します。

:secure

真を指定するとファイルの削除に FileUtils.#remove_entry_secure を使用します。

:mtime

時刻を Time か、起算時からの経過秒数を数値で指定します。

:parents

真を指定すると指定したディレクトリの親ディレクトリも含めて削除します。

:owner

ユーザー名か uid を指定すると所有ユーザを変更します。

:group

グループ名か gid を指定すると所有グループを指定します。

目次

特異メソッド
モジュール関数
定数

特異メソッド

collect_method(opt) -> Array[permalink][rdoc]

与えられたオプションを持つメソッド名の配列を返します。

[PARAM] opt:
オプション名をシンボルで指定します。
require 'fileutils'
FileUtils.collect_method(:preserve) # => ["cp", "cp_r", "copy", "install"]
commands -> Array[permalink][rdoc]

何らかのオプションを持つメソッド名の配列を返します。

require 'fileutils'
FileUtils.commands  # => ["chmod", "cp", "cp_r", "install", ...]
have_option?(mid, opt) -> bool[permalink][rdoc]

mid というメソッドが opt というオプションを持つ場合、真を返します。そうでない場合は、偽を返します。

[PARAM] mid:
メソッド名を指定します。
[PARAM] opt:
オプション名を指定します。
options -> Array[permalink][rdoc]

オプション名の配列を返します。

require 'fileutils'
FileUtils.options
# => ["noop", "verbose", "force", "mode", "parents", "owner", "group", "preserve", "dereference_root", "remove_destination", "secure", "mtime", "nocreate"]
options_of(mid) -> Array[permalink][rdoc]

与えられたメソッド名で使用可能なオプション名の配列を返します。

[PARAM] mid:
メソッド名を指定します。
require 'fileutils'
FileUtils.options_of(:rm)  # => ["noop", "verbose", "force"]

モジュール関数

cd(dir, options = {}) -> nil[permalink][rdoc]
cd(dir, options = {}) {|dir| .... } -> nil
chdir(dir, options = {}) -> nil
chdir(dir, options = {}) {|dir| .... } -> nil

プロセスのカレントディレクトリを dir に変更します。

ブロックとともに呼び出された時はブロック終了後に元のディレクトリに戻ります。

[PARAM] dir:
ディレクトリを指定します。
[PARAM] options:
:verbose が指定できます。 FileUtils/オプションの説明

例:

require 'fileutils'
FileUtils.cd('/', {:verbose => true})   # chdir and report it
chmod(mode, list, options = {}) -> Array[permalink][rdoc]

ファイル list のパーミッションを mode に変更します。

[PARAM] mode:
パーミッションを8進数(absolute mode)か文字列(symbolic mode)で指定します。
[PARAM] list:
ファイルのリストを指定します。 対象のファイルが一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:noop と :verbose が指定可能です。 FileUtils/オプションの説明
[RETURN]
list を配列として返します。

例:

# Absolute mode
require 'fileutils'
FileUtils.chmod(0644, %w(my.rb your.rb his.rb her.rb))
FileUtils.chmod(0755, 'somecommand')
FileUtils.chmod(0755, '/usr/bin/ruby', :verbose => true)
# Symbolic mode
require 'fileutils'
FileUtils.chmod("u=wr,go=rr", %w(my.rb your.rb his.rb her.rb))
FileUtils.chmod("u=wrx,go=rx", 'somecommand')
FileUtils.chmod("u=wrx,go=rx", '/usr/bin/ruby', :verbose => true)

symbolic mode では以下の指定を 操作対象 演算子 権限 の順番で指定します。

操作対象(複数指定可。省略した場合は a)。

演算子。

権限(複数指定可)。

chmod_R(mode, list, options = {}) -> Array[permalink][rdoc]

ファイル list のパーミッションを再帰的に mode へ変更します。

[PARAM] mode:
パーミッションを8進数(absolute mode)か文字列(symbolic mode)で指定します(FileUtils.#chmod 参照)。
[PARAM] list:
ファイルのリストを指定します。対象のファイルが一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:noop と :verbose が指定可能です。 FileUtils/オプションの説明
[RETURN]
list を配列として返します。

例:

require 'fileutils'
FileUtils.chmod_R(0700, '/tmp/removing')
chown(user, group, list, options = {}) -> Array[permalink][rdoc]

ファイル list の所有ユーザと所有グループを user と group に変更します。

user, group に nil または -1 を渡すとその項目は変更しません。

[PARAM] user:
ユーザー名か uid を指定します。nil/-1 を指定すると変更しません。
[PARAM] group:
グループ名か gid を指定します。nil/-1 を指定すると変更しません。
[PARAM] list:
ファイルのリストを指定します。対象のファイルが一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:noop と :verbose が指定可能です。 FileUtils/オプションの説明
[RETURN]
list を配列として返します。

例:

require 'fileutils'
FileUtils.chown 'root', 'staff', '/usr/local/bin/ruby'
FileUtils.chown nil, 'bin', Dir.glob('/usr/bin/*'), :verbose => true
chown_R(user, group, list, options = {}) -> Array[permalink][rdoc]

list 以下のファイルの所有ユーザと所有グループを user と group へ再帰的に変更します。

user, group に nil または -1 を渡すとその項目は変更しません。

[PARAM] user:
ユーザー名か uid を指定します。nil/-1 を指定すると変更しません。
[PARAM] group:
グループ名か gid を指定します。nil/-1 を指定すると変更しません。
[PARAM] list:
ファイルのリストを指定します。対象のファイルが一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:noop と :verbose が指定可能です。 FileUtils/オプションの説明
[RETURN]
list を配列として返します。

例:

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

require 'fileutils'
FileUtils.chown_R 'www', 'www', '/var/www/htdocs'
FileUtils.chown_R 'cvs', 'cvs', '/var/cvs', :verbose => true
cmp(file_a, file_b) -> bool[permalink][rdoc]
compare_file(file_a, file_b) -> bool
identical?(file_a, file_b) -> bool

ファイル file_a と file_b の内容が同じなら真を返します。

[PARAM] file_a:
ファイル名。
[PARAM] file_b:
ファイル名。

例:

require 'fileutils'
FileUtils.cmp('somefile', 'somefile')      #=> true
FileUtils.cmp('/dev/null', '/dev/urandom') #=> false
compare_stream(io_a, io_b) -> bool[permalink][rdoc]

IO オブジェクト io_a と io_b の内容が同じなら真を返します。

[PARAM] io_a:
IO オブジェクト。
[PARAM] io_b:
IO オブジェクト。
cp(src, dest, options = {}) -> ()[permalink][rdoc]
copy(src, dest, options = {}) -> ()

ファイル src を dest にコピーします。

src にファイルが一つだけ与えられた場合、 dest がディレクトリならdest/src にコピーします。 dest が既に存在ししかもディレクトリでないときは上書きします。

src にファイルが複数与えられた場合、 file1 を dest/file1 にコピー、file2 を dest/file2 にコピー、というように、ディレクトリ dest の中にファイル file1、file2 …を同じ名前でコピーします。dest がディレクトリでない場合は例外 Errno::ENOTDIR が発生します。

[PARAM] src:
コピー元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:
コピー先のファイルかディレクトリです。
[PARAM] options:
:preserve, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::ENOTDIR:
src が複数のファイルかつ、dest がディレクトリでない場合に発生します。

例:

require 'fileutils'
FileUtils.cp 'eval.c', 'eval.c.org'
FileUtils.cp(['cgi.rb', 'complex.rb', 'date.rb'], '/usr/lib/ruby/1.8')
FileUtils.cp(%w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.8', {:verbose => true})
copy_entry(src, dest, preserve = false, dereference_root = false) -> ()[permalink][rdoc]

ファイル src を dest にコピーします。

src が普通のファイルでない場合はその種別まで含めて完全にコピーします。 src がディレクトリの場合はその中身を再帰的にコピーします。

[PARAM] src:
コピー元。
[PARAM] dest:
コピー先。
[PARAM] preserve:
preserve が真のときは更新時刻と、可能なら所有ユーザ・所有グループもコピーします。
[PARAM] dereference_root:
dereference_root が真のときは src についてだけシンボリックリンクの指す内容をコピーします。偽の場合はシンボリックリンク自体をコピーします。
copy_file(src, dest, preserve = false, dereference_root = true) -> ()[permalink][rdoc]

ファイル src の内容を dest にコピーします。

[PARAM] src:
コピー元。
[PARAM] dest:
コピー先。
[PARAM] preserve:
preserve が真のときは更新時刻と、可能なら所有ユーザ・所有グループもコピーします。
[PARAM] dereference_root:
dereference_root が真のときは src についてだけシンボリックリンクの指す内容をコピーします。偽の場合はシンボリックリンク自体をコピーします。
copy_stream(src, dest) -> ()[permalink][rdoc]

src を dest にコピーします。 src には read メソッド、dest には write メソッドが必要です。

[PARAM] src:
read メソッドを持つオブジェクト。
[PARAM] dest:
write メソッドを持つオブジェクト。
cp_r(src, dest, options = {}) -> ()[permalink][rdoc]

src を dest にコピーします。src がディレクトリであったら再帰的にコピーします。その際 dest がディレクトリなら dest/src にコピーします。

[PARAM] src:
コピー元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:
コピー先のファイルかディレクトリです。
[PARAM] options:
:preserve, :noop, :verbose, :dereference_root, :remove_destination が指定できます。 FileUtils/オプションの説明

例:

# installing ruby library "mylib" under the site_ruby
require 'fileutils'
FileUtils.rm_r(site_ruby + '/mylib', {:force => true})
FileUtils.cp_r('lib/', site_ruby + '/mylib')
# other sample
require 'fileutils'
FileUtils.cp_r(%w(mail.rb field.rb debug/), site_ruby + '/tmail')
FileUtils.cp_r(Dir.glob('*.rb'), '/home/taro/lib/ruby',
               {:noop => true, :verbose => true})
pwd -> String[permalink][rdoc]
getwd -> String

プロセスのカレントディレクトリを文字列で返します。

install(src, dest, options = {}) -> ()[permalink][rdoc]

src と dest の内容が違うときだけ src を dest にコピーします。

[PARAM] src:
コピー元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:
コピー先のファイルかディレクトリです。
[PARAM] options:
:preserve, :noop, :verbose, :mode, :owner, :group が指定できます。 FileUtils/オプションの説明

例:

require 'fileutils'
FileUtils.install('ruby', '/usr/local/bin/ruby', {:mode => 0755, :verbose => true})
FileUtils.install('lib.rb', '/usr/local/lib/ruby/site_ruby', {:verbose => true})
link(src, dest, options = {}) -> ()

src へのハードリンク dest を作成します。

src が一つの場合、 dest がすでに存在しディレクトリであるときは dest/src を作成します。 dest がすでに存在しディレクトリでないならば例外 Errno::EEXIST が発生します。ただし :force オプションを指定したときは dest を上書きします。

src が複数の場合、 src[0] へのハードリンク dest/src[0]、src[1] へのハードリンク dest/src[1] …を作成します。 dest がディレクトリでない場合は例外 Errno::ENOTDIR が発生します。

[PARAM] src:
リンク元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:
リンク作成先のファイルかディレクトリです。
[PARAM] options:
:force, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::EEXIST:
src が一つで dest がすでに存在しディレクトリでない場合に発生します。
[EXCEPTION] Errno::ENOTDIR:
src が複数で dest がディレクトリでない場合に発生します。

例:

require 'fileutils'
FileUtils.ln('gcc', 'cc', {:verbose => true})
FileUtils.ln('/usr/bin/emacs21', '/usr/bin/emacs')
FileUtils.cd('/bin')
FileUtils.ln(%w(cp mv mkdir), '/usr/bin')
ln_s(src, dest, options = {}) -> ()[permalink][rdoc]
symlink(src, dest, options = {}) -> ()

src へのシンボリックリンク dest を作成します。

src が一つの場合、 dest がすでに存在しディレクトリであるときは dest/src を作成します。 dest がすでに存在しディレクトリでないならば例外 Errno::EEXIST が発生します。ただし :force オプションを指定したときは dest を上書きします。

src が複数の場合、 src[0] へのシンボリックリンク dest/src[0]、src[1] へのシンボリックリンク dest/src[1] …を作成します。 dest がディレクトリでない場合は例外 Errno::ENOTDIR が発生します。

[PARAM] src:
リンク元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:
リンク作成先のファイルかディレクトリです。
[PARAM] options:
:force, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::EEXIST:
src が一つで dest がすでに存在しディレクトリでない場合に発生します。
[EXCEPTION] Errno::ENOTDIR:
src が複数で dest がディレクトリでない場合に発生します。

例:

require 'fileutils'
FileUtils.ln_s('/usr/bin/ruby', '/usr/local/bin/ruby')
FileUtils.ln_s('verylongsourcefilename.c', 'c', {:force => true})
FileUtils.ln_s(Dir.glob('bin/*.rb'), '/home/aamine/bin')
ln_sf(src, dest, options = {}) -> ()[permalink][rdoc]

src へのシンボリックリンク dest を作成します。

ln_s(src, dest, :force => true) と同じです。

[PARAM] src:
リンク元。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:
リンク作成先のファイルかディレクトリです。
[PARAM] options:
:force, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[EXCEPTION] Errno::ENOTDIR:
src が複数で dest がディレクトリでない場合に発生します。

[SEE_ALSO] FileUtils.#ln_s

mkdir_p(list, options = {}) -> Array[permalink][rdoc]
mkpath(list, options = {}) -> Array
makedirs(list, options = {}) -> Array

ディレクトリ dir とその親ディレクトリを全て作成します。

例えば、

require 'fileutils'
FileUtils.mkdir_p('/usr/local/lib/ruby')

は以下の全ディレクトリを (なければ) 作成します。

[PARAM] list:
作成するディレクトリ。一つの場合は文字列でも指定できます。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:mode, :noop, :verbose が指定できます。 FileUtils/オプションの説明
[RETURN]
ディレクトリ名文字列の配列を返します。
mkdir(dir, options = {}) -> ()[permalink][rdoc]

ディレクトリ dir を作成します。

[PARAM] dir:
作成するディレクトリ。
[PARAM] options:
:mode, :noop, :verbose が指定できます。 FileUtils/オプションの説明

例:

require 'fileutils'
FileUtils.mkdir('test')
FileUtils.mkdir(%w( tmp data ))
FileUtils.mkdir('notexist', {:noop => true})  # does not create really
mv(src, dest, options = {}) -> ()[permalink][rdoc]
move(src, dest, options = {}) -> ()

ファイル src を dest に移動します。

src が一つの場合、 dest がすでに存在しディレクトリであるときは src を dest/src へ移動します。 dest がすでに存在しディレクトリでないときは src は dest を上書きします。

src が複数の場合、 src[0] を dest/src[0]、src[1] を dest/src[1] へ移動します。 dest がディレクトリでない場合は例外 Errno::ENOTDIR が発生します。

[PARAM] src:
元のファイル。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] dest:
移動先のファイル、またはディレクトリ。
[PARAM] options:
:force, :noop, :verbose, :secure が指定できます。 FileUtils/オプションの説明

例:

require 'fileutils'
FileUtils.mv('badname.rb', 'goodname.rb')
FileUtils.mv('stuff.rb', 'lib/ruby', {:force => true})
FileUtils.mv(['junk.txt', 'dust.txt'], "#{ENV['HOME']}/.trash")
FileUtils.mv(Dir.glob('test*.rb'), 'test', {:noop => true, :verbose => true} )
rm(list, options = {}) -> ()[permalink][rdoc]
remove(list, options = {}) -> ()

list で指定された対象を消去します。

[PARAM] list:
削除する対象。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:force, :noop, :verbose が指定できます。 FileUtils/オプションの説明

例:

require 'fileutils'
FileUtils.rm('junk.txt')
FileUtils.rm(Dir.glob('*~'))
FileUtils.rm('NotExistFile', {:force => true})    # never raises exception
remove_dir(path, force = false) -> ()[permalink][rdoc]

ディレクトリ path を削除します。

[PARAM] path:
削除するディレクトリ。
[PARAM] force:
真のときは削除中に発生した StandardError を無視します。
remove_entry(path, force = false) -> ()[permalink][rdoc]

ファイル path を削除します。path がディレクトリなら再帰的に削除します。

このメソッドにはローカル脆弱性が存在します。詳しくは FileUtils.#remove_entry_secure の項を参照してください。

[PARAM] path:
削除するパス。
[PARAM] force:
真のときは削除中に発生した StandardError を無視します。

例:

require 'fileutils'
FileUtils.remove_entry '/tmp/ruby.tmp.08883'

[SEE_ALSO] FileUtils.#remove_entry_secure

remove_entry_secure(path, force = false) -> ()[permalink][rdoc]

ファイル path を削除します。path がディレクトリなら再帰的に削除します。

FileUtils.#rm_r および FileUtils.#remove_entry には TOCTTOU (time-of-check to time-of-use)脆弱性が存在します。このメソッドはそれを防ぐために新設されました。 FileUtils.#rm_r および FileUtils.#remove_entry は以下の条件が満たされるときにはセキュリティホールになりえます。

この脆弱性を防ぐため、remove_entry_secure は削除前に path 以下のディレクトリのオーナーとパーミッションを変更し、上記の条件を回避します。ただし remove_entry_secure は親ディレクトリが以下の条件を満たすことを仮定しています。

この条件が満たされない場合 remove_entry_secure は安全ではありません。

[PARAM] path:
削除するパス。
[PARAM] force:
真のときは削除中に発生した StandardError を無視します。
remove_file(path, force = false) -> ()[permalink][rdoc]

ファイル path を削除します。

[PARAM] path:
削除するファイル。
[PARAM] force:
真のときは削除中に発生した StandardError を無視します。
rm_f(list, options = {}) -> ()[permalink][rdoc]
safe_unlink(list, options = {}) -> ()

FileUtils.rm(list, :force => true) と同じです。

FileUtils/オプションの説明

[PARAM] list:
削除する対象。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:noop, :verbose が指定できます。 :force がセットされた場合は作業中すべての StandardError を無視します。

[SEE_ALSO] FileUtils.#rm

rm_r(list, options = {}) -> ()[permalink][rdoc]

ファイルまたはディレクトリ list を再帰的に消去します。

[PARAM] list:
削除する対象。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:force, :noop, :verbose, :secure が指定できます。 FileUtils/オプションの説明

注意

このメソッドにはローカル脆弱性が存在します。この脆弱性を回避するには :secure オプションを使用してください。詳しくは FileUtils.#remove_entry_secure の項を参照してください。

例:

require 'fileutils'
FileUtils.rm_r(Dir.glob('/tmp/*'))
FileUtils.rm_r(Dir.glob('/tmp/*'), :secure => true)

[SEE_ALSO] FileUtils.#rm, FileUtils.#remove_entry_secure

rm_rf(list, options = {}) -> ()[permalink][rdoc]
rmtree(list, options = {}) -> ()

ファイルまたはディレクトリ list を再帰的に消去します。

rm_r(list, {:force => true}) と同じです。

[PARAM] list:
削除する対象。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:noop, :verbose, :secure が指定できます。 FileUtils/オプションの説明

注意

このメソッドにはローカル脆弱性が存在します。この脆弱性を回避するには :secure オプションを使用してください。詳しくは FileUtils.#remove_entry_secure の項を参照してください。

[SEE_ALSO] FileUtils.#rm, FileUtils.#rm_r, FileUtils.#remove_entry_secure

rmdir(dir, options = {}) -> ()[permalink][rdoc]

ディレクトリ dir を削除します。

ディレクトリにファイルが残っていた場合は削除に失敗します。

[PARAM] dir:
削除するディレクトリを指定します。一つの場合は文字列でも指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:parents, :noop, :verbose が指定できます。 FileUtils/オプションの説明

例:

require 'fileutils'
FileUtils.rmdir('somedir')
FileUtils.rmdir(%w(somedir anydir otherdir))
# 実際にはディレクトリの削除は行わずにメッセージ出力のみ
FileUtils.rmdir('somedir', {:verbose => true, :noop => true})
touch(list, options = {}) -> ()[permalink][rdoc]

list で指定されたファイルの最終変更時刻 (mtime) とアクセス時刻 (atime) を変更します。

list で指定されたファイルが存在しない場合は空のファイルを作成します。

[PARAM] list:
対象のファイル。一つの場合は文字列も指定可能です。二つ以上指定する場合は配列で指定します。
[PARAM] options:
:mtime, :nocreate, :noop, :verbose が指定できます。 FileUtils/オプションの説明

例:

require 'fileutils'
FileUtils.touch('timestamp')
FileUtils.touch('timestamp', :mtime => Time.now)
FileUtils.touch(Dir.glob('*.c'))
uptodate?(newer, older_list, options = nil) -> bool[permalink][rdoc]

newer が、older_list に含まれるすべてのファイルより新しいとき真。存在しないファイルは無限に古いとみなされます。

[PARAM] newer:
ファイルを一つ指定します。
[PARAM] older_list:
ファイル名の配列を指定します。
[PARAM] options:
どのようなオプションも指定することはできません。
[EXCEPTION] ArgumentError:
options にオプションを指定した場合に発生します。

例:

require 'fileutils'
FileUtils.uptodate?('hello.o', ['hello.c', 'hello.h']) or system('make')

定数

METHODS -> Array[permalink][rdoc]

このモジュールで定義されている公開メソッドの配列を返します。

OPT_TABLE -> Hash[permalink][rdoc]

内部で使用します。