FileUtils 모듈

FileUtils 모듈 (FileUtils)

파일을 복사·이동·삭제하는 등의 파일 유틸리티 메서드를 제공하는 네임스페이스예요. FileUtils는 Object에서 상속받고, File 클래스를 보완해요(그러나 File에 include·extend되지는 않아요).

출처: Ruby 3.3 API

본문

FileUtils의 메서드들은 크게 생성, 삭제, 조회, 설정, 비교, 복사, 이동, 옵션으로 나뉘어요.

메서드 요약 (What's Here)

  • Creating: ::mkdir(디렉토리 생성), ::mkdir_p·::makedirs·::mkpath(상위 디렉토리도 필요 시 생성), ::link_entry(하드 링크), ::ln·::link(하드 링크들), ::ln_s·::symlink(심볼릭 링크), ::ln_sf(필요 시 덮어쓰며 링크), ::ln_sr(대상에 상대적인 링크)
  • Deleting: ::remove_dir, ::remove_entry, ::remove_entry_secure, ::remove_file, ::rm·::remove, ::rm_f·::safe_unlink, ::rm_r, ::rm_rf·::rmtree, ::rmdir
  • Querying: ::pwd·::getwd(작업 디렉토리 경로), ::uptodate?(항목이 다른 항목보다 새로운지)
  • Setting: ::cd·::chdir(작업 디렉토리 설정), ::chmod, ::chmod_R, ::chown, ::chown_R, ::touch
  • Comparing: ::compare_file·::cmp·::identical?, ::compare_stream
  • Copying: ::copy_entry, ::copy_file, ::copy_stream, ::cp·::copy, ::cp_lr, ::cp_r, ::install
  • Moving: ::mv·::move
  • Options: ::collect_method, ::commands, ::have_option?, ::options, ::options_of

경로 인자 (Path Arguments)

일부 FileUtils 메서드는 경로 인자를 받는데, 파일시스템 항목의 경로로 해석돼요. 문자열이면 그 값이 경로이고, :to_path 메서드가 있으면 그걸로 변환하며, :to_str 메서드가 있으면 그걸로 변환해요.

공통 키워드 옵션

대부분의 메서드가 공통 키워드 인자를 받아요.

  • verbose: true — 동등한 명령을 출력해요.
  • noop: true — 실제로는 수행하지 않고(변경 없음) nil을 돌려줘요.
  • force: — 일부 메서드에서 존재하지 않는 경로를 무시.
  • secure: true — 특정 메서드에서 안전한 삭제(remove_entry_secure)를 사용.

TOCTTOU 취약점 피하기 (Avoiding the TOCTTOU Vulnerability)

특정 재귀 삭제 메서드에는 "check-to-use 사이의 시간" 취약점인 TOCTTOU가 있을 수 있어요. 대상 경로의 조상 디렉토리가 world writable(/tmp 포함)이거나, 대상 트리에 world-writable 하위 디렉토리나 심볼릭 링크가 있으면 위험해요. 이를 피하려면 FileUtils.remove_entry_secure를 사용할 수 있고, FileUtils.rm_r·rm_rf에 secure: true를 주거나 FileUtils.mv에 secure: true를 주면 됩니다.

Public Class Methods

  • cd(dir, verbose: nil) { |dir| ... } (별칭 chdir) — 작업 디렉토리를 dir로 변경. 블록이 없으면 현재 디렉토리를 변경하고 0을 반환. 블록이 있으면 dir로 변경 후 블록을 호출하고 원래 디렉토리를 복원한 뒤 블록 값을 반환. 
    FileUtils.pwd                                     # => "/rdoc/fileutils"
FileUtils.cd('..') { |arg| [arg, FileUtils.pwd] } # => ["..", "/rdoc"]
FileUtils.pwd                                     # => "/rdoc/fileutils"
  • chmod(mode, list, noop: nil, verbose: nil) — list의 경로 항목 권한을 mode로 변경. 일반 파일은 File.chmod, 심볼릭 링크는 File.lchmod 사용. mode는 정수(권한 비트) 또는 문자열(예: 'u=wrx,go=rx', targets u/g/o/a, operator +/-/=, perms r/w/x/X/s/t)일 수 있어요. 
    FileUtils.chmod(0755, 'src0.txt')
FileUtils.chmod('u=wrx,go=rx', 'src1.txt')
  • chmod_R(mode, list, noop: nil, verbose: nil, force: nil) — 항목과 그 하위까지 권한 재귀 변경.
  • chown(user, group, list, noop: nil, verbose: nil) — 항목의 소유자·그룹 변경.
  • chown_R(user, group, list, noop: nil, verbose: nil, force: nil) — 항목과 하위까지 재귀 변경.
  • collect_method(opt) — 주어진 옵션을 받아들이는 메서드 이름 배열을 반환.
  • commands() — 옵션을 받아들이는 메서드 이름 배열을 반환.
  • compare_file(a, b) (별칭 cmp, identical?) — 두 항목의 내용이 동일하면 true.
  • compare_stream(a, b) — 두 스트림의 내용이 동일하면 true.
  • copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false) — 항목을 재귀 복사.
  • copy_file(src, dest, preserve = false, dereference = true) — 항목 복사.
  • copy_stream(src, dest) — 스트림 복사.
  • cp(src, dest, preserve: nil, noop: nil, verbose: nil) (별칭 copy) — 파일 복사.
  • cp_lr(src, dest, noop: nil, verbose: nil, dereference_root: true, remove_destination: false) — 재귀적으로 하드 링크 생성.
  • cp_r(src, dest, preserve: nil, noop: nil, verbose: nil, dereference_root: true, remove_destination: nil) — 파일 재귀 복사. 모드·소유자·그룹이 유지돼요. 이것을 바꾸려면 FileUtils.install을 사용.
  • have_option?(mid, opt) — 메서드 mid가 옵션 opt를 받는지.
  • install(src, dest, mode: nil, owner: nil, group: nil, preserve: nil, noop: nil, verbose: nil) — install(1)처럼 파일을 재귀 복사하고, 선택적으로 모드·소유자·그룹 설정.
  • link_entry(src, dest, dereference_root = false, remove_destination = false) — 하드 링크 생성.
  • ln(src, dest, force: nil, noop: nil, verbose: nil) (별칭 link) — 하드 링크 생성.
  • ln_s(src, dest, force: nil, relative: false, target_directory: true, noop: nil, verbose: nil) (별칭 symlink) — 심볼릭 링크 생성. relative: true면 상대 링크.
  • ln_sf(src, dest, noop: nil, verbose: nil) — 필욕시 덮어쓰며 심볼릭 링크 생성.
  • ln_sr(src, dest, target_directory: true, force: nil, noop: nil, verbose: nil) — 대상에 상대적인 심볼릭 링크 생성.
  • mkdir(list, mode: nil, noop: nil, verbose: nil) — 디렉토리 생성.
  • mkdir_p(list, mode: nil, noop: nil, verbose: nil) (별칭 makedirs, mkpath) — 상위 디렉토리도 필요 시 생성하며 디렉토리 생성.
  • mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil) (별칭 move) — 항목 이동. secure: true고 src와 dest가 다른 파일시스템이면 remove_entry_secure를 사용해 "이동"을 수행.
  • options() — 모든 옵션 이름 배열을 반환.
  • options_of(mid) — 메서드 mid의 옵션 이름 배열을 반환.
  • pwd() (별칭 getwd) — 작업 디렉토리 경로를 반환.
  • remove_dir(path, force = false) — 디렉토리와 그 하위를 제거.
  • remove_entry(path, force = false) — 항목을 제거(디렉토리면 하위 포함).
  • remove_entry_secure(path, force = false) — remove_entry와 같되 안전하게 제거(재귀, TOCTTOU 방지 전처리 적용).
  • remove_file(path, force = false) — 파일 항목 제거.
  • rm(list, force: nil, noop: nil, verbose: nil) (별칭 remove) — 항목 제거.
  • rm_f(list, noop: nil, verbose: nil) (별칭 safe_unlink) — rm과 같되 강제로 제거(존재하지 않아도 오류 없음).
  • rm_r(list, force: nil, noop: nil, verbose: nil, secure: nil) — 항목과 하위를 제거.
  • rm_rf(list, noop: nil, verbose: nil, secure: nil) (별칭 rmtree) — rm_r과 같되 강제로 제거.
  • rmdir(list, parents: nil, noop: nil, verbose: nil) — 디렉토리 제거(parents: true면 비워진 상위도 제거).
  • touch(list, noop: nil, verbose: nil, mtime: nil, nocreate: nil) — 수정·접근 시간을 설정(필요시 생성). mtime으로 시간 지정.
  • uptodate?(new, old_list) — new가 old_list의 각 항목보다 새로우면 true.