class Pathname

Returns a new Pathname object containing the path to the current working directory (equivalent to Pathname.new(Dir.getwd)):

Pathname.getwd # => #<Pathname:/home>

Selects filesystem entries based on the given keyword arguments base, flags, and sort; see Filename Globbing.

With no block given, returns an array of pathnames, each based on a selected filesystem entry.

With a block given, calls the block with pathnames, each based on a selected filesystem entry.

Creates:

• A temporary directory via Dir.mktmpdir.

• A Pathname object that contains the path to that directory.

With no block given, returns the created pathname; the caller should delete the created directory when it is no longer needed (FileUtils.rm_r is a convenient method for the deletion):

pathname = Pathname.mktmpdir
dirpath = pathname.to_s
Dir.exist?(dirpath) # => true
# Do something with the directory.
require 'fileutils'
FileUtils.rm_r(dirpath)

With a block given, calls the block with the created pathname; on block exit, automatically deletes the created directory and all its contents; returns the block’s exit value:

pathname = Pathname.mktmpdir do |p|
  # Do something with the directory.
  p
end
Dir.exist?(pathname.to_s) # => false

Returns a new Pathname object based on the given path, via File.path(path).dup. the path may be a String, a File, a Dir, or another Pathname; see File.path:

Pathname.new('.')               # => #<Pathname:.>
Pathname.new('/usr/bin')        # => #<Pathname:/usr/bin>
Pathname.new(File.new('LEGAL')) # => #<Pathname:LEGAL>
Pathname.new(Dir.new('.'))      # => #<Pathname:.>
Pathname.new(Pathname.new('.')) # => #<Pathname:.>

Returns a new Pathname object based on the content of self and other; argument other may be a String, a File, a Dir, or another Pathname:

pn = Pathname('foo')     # => #<Pathname:foo>
pn + 'bar'               # => #<Pathname:foo/bar>
pn + File.new('LEGAL')   # => #<Pathname:foo/LEGAL>
pn + Dir.new('lib')      # => #<Pathname:foo/lib>
pn + Pathname('bar')     # => #<Pathname:foo/bar>

When other specifies a relative path (see relative?), it is combined with self to form a new pathname:

Pathname('/a/b') + 'c' # => #<Pathname:/a/b/c>

Extra component separators ('/') are removed:

Pathname('/a/b/') + 'c' # => #<Pathname:/a/b/c>

Extra current-directory components ('.') are removed:

Pathname('a') + '.' # => #<Pathname:a>
Pathname('.') + 'a' # => #<Pathname:a>
Pathname('.') + '.' # => #<Pathname:.>

Parent-directory components ('..') are:

• Resolved, when possible:

  Pathname('a')      + '..'      # => #<Pathname:.>
  Pathname('a/b')    + '..'      # => #<Pathname:a>
  Pathname('/')      + '../a'    # => #<Pathname:/a>
  Pathname('a')      + '../b'    # => #<Pathname:b>
  Pathname('a/b')    + '../c'    # => #<Pathname:a/c>
  Pathname('a//b/c') + '../d//e' # => #<Pathname:a//b/d//e>
  

• Removed, when not needed:

  Pathname('/') + '..' # => #<Pathname:/>
  

• Retained, when needed:

  Pathname('..') + '..'   # => #<Pathname:../..>
  Pathname('..') + '../a' # => #<Pathname:../../a>
  

When other specifies an absolute path (see absolute?), equivalent to Pathname(other.to_s):

Pathname('/a') + '/b/c' # => #<Pathname:/b/c>

Occurrences of '/', '.', and '..' are preserved:

Pathname('/a') + '//b//c/./../d' # => #<Pathname://b//c/./../d>

This method does not access the file system, so other need not represent an existing (or even a valid) file or directory path:

Pathname('/var') + 'nosuch:ever' # => #<Pathname:/var/nosuch:ever>

Compares the contents of self and other as strings; see String#<=>.

Returns:

• -1 if self‘s string is smaller than other’s string.

• 0 if the two are equal.

• 1 if self‘s string is larger than other’s string.

• nil if other is not a Pathname.

Examples:

Pathname('a')  <=> Pathname('b')  # => -1
Pathname('a')  <=> Pathname('ab') # => -1
Pathname('a')  <=> Pathname('a')  # => 0
Pathname('b')  <=> Pathname('a')  # => 1
Pathname('ab') <=> Pathname('a')  # => 1
Pathname('ab') <=> 'a'            # => nil

Two pathnames that are different may refer to the same entry in the filesystem:

Pathname('lib') <=> Pathname('./lib') # => 1

Returns whether the stored paths in self and other are equal:

pn = Pathname('lib')
pn == Pathname('lib')   # => true
pn == Pathname('./lib') # => false

Returns false if other is not a pathname:

pn == 'lib'             # => false

Returns whether self contains an absolute path:

Pathname('/home').absolute? # => true
Pathname('lib').absolute?   # => false

The result is OS-dependent for some paths:

Pathname('C:/').absolute?   # => true   # On Windows.
Pathname('C:/').absolute?   # => false  # Elsewhere.

With a block given, yields self, then a new pathname for each successive dirname in the stored path; see File.dirname:

Pathname('/path/to/some/file.rb').ascend {|dirname| p dirname}
#<Pathname:/path/to/some/file.rb>
#<Pathname:/path/to/some>
#<Pathname:/path/to>
#<Pathname:/path>
#<Pathname:/>

With no block given, returns a new Enumerator.

Returns a Time object containing the access time of the entry represented by self, as reported by the filesystem; see File System Access Time:

# Pathname for a (non-existent) directory.
dir_pn = Pathname('doc/foo')   # => #<Pathname:doc/foo>
# Create directory; establishes atime for directory.
dir_pn.mkdir
dir_pn.atime                   # => 2026-06-17 10:10:20.801115774 -0500
# Pathname for a (non-existent) file in the directory.
file_pn = dir_pn.join('t.tmp') # => #<Pathname:doc/foo/t.tmp>
# Create file; establishes atime for file, updates atime for directory.
file_pn.write('foo')
file_pn.atime                  # => 2026-06-17 10:11:40.987171568 -0500
dir_pn.atime                   # => 2026-06-17 10:11:40.96617277 -0500
# Write file; updates atime for file,but not directory.
file_pn.write('bar')
file_pn.atime                  # => 2026-06-17 10:13:22.062904563 -0500
dir_pn.atime                   # => 2026-06-17 10:11:40.96617277 -0500
# Read file; may update atime for file, but not directory.
file_pn.read
file_pn.atime                  # => 2026-06-17 10:13:22.062904563 -0500
dir_pn.atime                   # => 2026-06-17 10:11:40.96617277 -0500
# Clean up.
file_pn.delete
dir_pn.rmdir

Returns a new Pathname object containing all or part of the last entry of the path represented by self. Entries are delimited by the value of constant File::SEPARATOR and, if non-nil, the value of constant File::ALT_SEPARATOR.

When suffix is the empty string '', returns all of the last entry:

Pathname.new('foo/bar/baz/bat.txt').basename # => #<Pathname:bat.txt>
Pathname.new('foo/bar/baz').basename         # => #<Pathname:baz>

File::SEPARATOR                              # => "/"
Pathname.new('foo/bar.txt////').basename     # => #<Pathname:bar.txt>
File::ALT_SEPARATOR # => "\\"                # On Windows.
Pathname.new('foo/bar.txt//\\\\//').basename # => #<Pathname:bar.txt>

When suffix is '.*', the last filename extension, if any, is removed:

Pathname.new('foo/bar.txt').basename('.*')     # => #<Pathname:bar>
Pathname.new('foo/bar.txt.old').basename('.*') # => #<Pathname:bar.txt>
Pathname.new('foo/bar').basename('.*')         # => #<Pathname:bar>

When suffix is any string other than '' or '.*', the matching trailing substring, if any, is removed:

Pathname.new('foo/bar.txt').basename('.txt') # => #<Pathname:bar>
Pathname.new('foo/bar.txt').basename('txt')  # => #<Pathname:bar.>
Pathname.new('foo/bar.txt').basename('*')    # => #<Pathname:bar.txt>
Pathname.new('foo/bar.txt').basename('.')    # => #<Pathname:bar.txt>

Behaves like read, except that the file is opened in binary mode with ASCII-8BIT encoding.

Behaves like write, except that the file is opened in binary mode with ASCII-8BIT encoding.

Returns a new Time object containing the create time of the entry represented by self; see File System Timestamps:

# A directory and its Pathname.
dir_path = 'doc/foo'
dir_pn = Pathname(dir_path)
# Create directory; directory birthtime established.
dir_pn.mkdir
dir_pn.birthtime  # => 2026-06-16 17:06:10.779192552 -0500
# A file therein and its Pathname.
file_path = dir_pn.join('t.tmp')
file_pn = Pathname(file_path)
# Create file; file birthtime established; directory birthtime not updated.
file_pn.write('foo')
dir_pn.birthtime  # => 2026-06-16 17:06:10.779192552 -0500
file_pn.birthtime # => 2026-06-16 17:07:59.339330622 -0500
# Modify file; neither birthtime updated.
file_pn.write('bar')
dir_pn.birthtime  # => 2026-06-16 17:06:10.779192552 -0500
file_pn.birthtime # => 2026-06-16 17:07:59.339330622 -0500
# Clean up.
dir_pn.rmtree

Returns whether self represents a path to a block device (i.e., a direct-access device):

Pathname('/dev/nvme0n1').blockdev? # => true
Pathname('/dev/loop0').blockdev?   # => true
Pathname('/dev/tty').blockdev?     # => false
Pathname('/dev/null').blockdev?    # => false
Pathname('nosuch').blockdev?       # => false
Pathname($stdin).blockdev?         # => false

The returned value is OS-dependent; on Windows, almost always false.

Returns whether self represents a path to a character device (i.e., a sequential-access device):

Pathname('/dev/tty').chardev?     # => true
Pathname('/dev/null').chardev?    # => true
Pathname('/dev/nvme0n1').chardev? # => false
Pathname('/dev/loop0').chardev?   # => false
Pathname($stdin).chardev?         # => false
Pathname('nosuch').chardev?       # => false

The returned value is OS-dependent; on Windows, almost always false.

Returns an array of pathnames; each represents a child of the entry represented by self, which must be an existing directory in the underlying file system.

With with_dirnames given as true (the default), each pathname contains the full entry:

Pathname('lib').children.size # => 72
Pathname('lib').children.take(3)
# => [#<Pathname:lib/bundled_gems.rb>, #<Pathname:lib/bundler>, #<Pathname:lib/bundler.rb>]

With with_dirnames given as false, each pathname contains only the basename of the entry:

Pathname('lib').children(false).take(3)
# => [#<Pathname:bundled_gems.rb>, #<Pathname:bundler>, #<Pathname:bundler.rb>]

Note that entries . and .. in directory are not actually children, and so are never included in the result.

Changes the mode (i.e., permissions) of the entry represented by self; see File Permissions:

# Pathname for a (non-existent) directory.
dir_pn = Pathname('doc/foo') # => #<Pathname:doc/foo>
# Create the directory and fetch its mode.
dir_pn.mkdir
dir_pn.stat.mode.to_s(8) # => "40775"
# Change the directory mode and fetch the new mode.
dir_pn.chmod(0777)
dir_pn.stat.mode.to_s(8) # => "40777"

# Pathname for a (non-existent) file in the directory.
file_pn = dir_pn.join('t.tmp') # => #<Pathname:doc/foo/t.tmp>
# Create the file and fetch its mode.
file_pn.write('foo')
file_pn.stat.mode.to_s(8) # => "100664"
# Change the file mode and fetch its new mode.
file_pn.chmod(0777)
file_pn.stat.mode.to_s(8) # => "100777"

# Clean up.
file_pn.delete
dir_pn.rmdir

Changes the owner and group of an entry (directory or file):

# Super user; all privileges.
Process.uid                    # => 0
Process.gid                    # => 0

# Pathname for a (non-existent) directory.
dir_pn = Pathname('doc/foo')   # => #<Pathname:doc/foo>
# Create the directory; fetch original owner and group.
dir_pn.mkdir
dir_stat = dir_pn.stat
dir_stat.uid                   # => 0
dir_stat.gid                   # => 0
# Change owner; fetch current owner and group.
dir_pn.chown(1000, 1000)
dir_stat = dir_pn.stat
dir_stat.uid                   # => 1000
dir_stat.gid                   # => 1000

Pathname for a (non-existent) file in the directory.
file_pn = dir_pn.join('t.tmp') # => #<Pathname:doc/foo/t.tmp>
# Create the directory; fetch original owner and group.
file_pn.write('foo')
file_stat = file_pn.stat
file_stat.uid                  # => 0
file_stat.gid                  # => 0
# Change owner; fetch current owner and group.
file_pn.chown(1000, 1000)
file_stat = file_pn.stat
file_stat.uid                  # => 1000
file_stat.gid                  # => 1000
# Clean up.
file_pn.delete
dir_pn.rmdir

Notes:

• On Windows, the owner and group are not changed.

• Only a process with superuser privileges can change the owner of an entry.

• The owner of an entry can change its group to any group to which the owner belongs.

• A +nil+ or +-1+ owner or group id is ignored.

• The method follows symbolic links to the target entry.

Returns a new Pathname object, “cleaned” of unnecessary separators, single-dot entries, and double-dot entries.

When self is empty, returns a pathname with a single-dot entry:

Pathname('').cleanpath # => #<Pathname:.>

Separators

A lone separator is preserved:

Pathname('/').cleanpath # => #<Pathname:/>

Multiple trailing separators are removed:

Pathname('foo/////').cleanpath # => #<Pathname:foo>
Pathname('foo/').cleanpath     # => #<Pathname:foo>

Multiple embedded separators are reduced to a single separator:

Pathname('foo///bar').cleanpath # => #<Pathname:foo/bar>

Multiple leading separators are reduced:

# On Windows, where File.dirname('//') == '//'.
Pathname('/////foo').cleanpath # => #<Pathname://foo>
Pathname('/////').cleanpath    # => #<Pathname://>
# Otherwise, where File.dirname('//') == '/'.
Pathname('/////foo').cleanpath # => #<Pathname:/foo>
Pathname('/////').cleanpath    # => #<Pathname:/>

Single-Dot Entries

A lone single-dot entry is preserved:

Pathname('.').cleanpath  # => #<Pathname:.>

A non-lone single-dot entry, regardless of its location, is removed:

Pathname('foo/././././bar').cleanpath  # => #<Pathname:foo/bar>
Pathname('./foo/./././bar').cleanpath  # => #<Pathname:foo/bar>
Pathname('foo/./././bar/./').cleanpath # => #<Pathname:foo/bar>

Double-Dot Entries

A lone double-dot entry is preserved:

Pathname('..').cleanpath # => #<Pathname:..>

When a non-lone double-dot entry is preceded by a named entry, both are removed:

Pathname('foo/..').cleanpath          # => #<Pathname:.>
Pathname('foo/../bar').cleanpath      # => #<Pathname:bar>
Pathname('foo/../bar/..').cleanpath   # => #<Pathname:.>
Pathname('foo/bar/./../..').cleanpath # => #<Pathname:.>

When a non-lone double-dot entry is not preceded by a named entry, it is preserved:

Pathname('../..').cleanpath # => #<Pathname:../..>

A non-lone meaningless double-dot entry is removed:

Pathname('/..').cleanpath    # => #<Pathname:/>
Pathname('/../..').cleanpath # => #<Pathname:/>

Symbolic Links

If the path may contain symbolic links, consider give optional argument symlinks as true; the method then uses a more conservative algorithm that avoids breaking symbolic links. This may preserve more double-dot entries than are absolutely necessary, but without accessing the filesystem, this can’t be avoided.

Examples:

Pathname('a/').cleanpath           # => #<Pathname:a>
Pathname('a/').cleanpath(true)     # => #<Pathname:a/>

Pathname('a/.').cleanpath          # => #<Pathname:a>
Pathname('a/.').cleanpath(true)    # => #<Pathname:a/.>

Pathname('a/./').cleanpath         # => #<Pathname:a>
Pathname('a/./').cleanpath(true)   # => #<Pathname:a/.>

Pathname('a/b/.').cleanpath        # => #<Pathname:a/b>
Pathname('a/b/.').cleanpath(true)  # => #<Pathname:a/b/.>

Pathname('a/../.').cleanpath       # => #<Pathname:.>
Pathname('a/../.').cleanpath(true) # => #<Pathname:a/..>

Pathname('a/b/../../../../c/../d').cleanpath
# => #<Pathname:../../d>
Pathname('a/b/../../../../c/../d').cleanpath(true)
# => #<Pathname:a/b/../../../../c/../d>

On Windows, returns the birthtime.

On other systems, returns a new Time object containing the time of the most recent metadata change to the entry represented by self; see File System Timestamps:

# A directory and its Pathname.
dir_path = 'doc/foo'
dir_pn = Pathname(dir_path)
# Create directory; directory ctime established.
dir_pn.mkdir
dir_pn.ctime  # => 2026-06-16 16:44:15.86720572 -0500
# A file therein and its Pathname.
file_path = dir_pn.join('t.tmp')
file_pn = Pathname(file_path)
# Create file; file ctime established; directory ctime updated.
file_pn.write('foo')
file_pn.ctime # => 2026-06-16 16:46:00.734974872 -0500
dir_pn.ctime  # => 2026-06-16 16:46:00.734974872 -0500
# Write file; file ctime updated; directory ctime not updated.
file_pn.write('bar')
file_pn.ctime # => 2026-06-16 16:49:11.421204188 -0500
dir_pn.ctime  # => 2026-06-16 16:46:00.734974872 -0500
# Read file; neither ctime updated.
file_pn.read
file_pn.ctime # => 2026-06-16 16:49:11.421204188 -0500
dir_pn.ctime  # => 2026-06-16 16:46:00.734974872 -0500
# Clean up.
dir_pn.rmtree

With a block given, yields a new pathname for each successive dirname in the stored path; see File.dirname:

# Absolute path.
Pathname('/path/to/some/file.rb').descend {|pn| p pn }
# #<Pathname:/>
# #<Pathname:/path>
# #<Pathname:/path/to>
# #<Pathname:/path/to/some>
# #<Pathname:/path/to/some/file.rb>
# Relative path.
Pathname('path/to/some/file.rb').descend {|pn| p pn }
# #<Pathname:path>
# #<Pathname:path/to>
# #<Pathname:path/to/some>
# #<Pathname:path/to/some/file.rb>

With no block given, returns a new Enumerator.

Returns whether the entry represented by self is a directory:

Pathname('/etc').directory?      # => true
Pathname('lib').directory?       # => true
Pathname('README.md').directory? # => false
Pathname('nosuch').directory?    # => false

Returns a new pathname whose path is all but the last component of the path in self:

Pathname('/usr/lib/linux').basename # => #<Pathname:linux>
Pathname('/usr').basename           # => #<Pathname:usr>
Pathname('/').basename              # => #<Pathname:/>
Pathname('lib/').basename           # => #<Pathname:lib>
Pathname('nosuch').basename         # => #<Pathname:nosuch>

With a block given and with_dirnames given as true (the default), yields a new pathname for each child of the entry represented by self; returns an array of those pathnames:

Pathname('include').each_child {|child| p child }
# #<Pathname:include/ruby>
# #<Pathname:include/ruby.h>
# => [#<Pathname:include/ruby>, #<Pathname:include/ruby.h>]

With a block given and with_dirnames given as false, yields a new pathname for each child of the entry represented by self with its dirname omitted; returns an array of those pathnames:

Pathname('include').each_child(false) {|child| p child }
# #<Pathname:ruby>
# #<Pathname:ruby.h>
# => [#<Pathname:ruby>, #<Pathname:ruby.h>]

Note that entries '.' and '..' are not children.

With no block given, returns a new Enumerator.

With a block given, yields a new pathname for each entry in the entry represented by self; returns nil:

Pathname('include').each_entry {|entry| p entry }
# #<Pathname:ruby>
# #<Pathname:..>
# #<Pathname:ruby.h>
# #<Pathname:.>
# => nil

With no block given, returns a new Enumerator.

With a block given, yields each component of the string path:

Pathname('/foo/bar/baz').each_filename {|filename| p filename }
=> nil

Output:

"foo"
"bar"
"baz"

With no block given, returns a new Enumerator.

With a block given, calls the block with each line from the file represented by self; returns nil:

lines = []
Pathname('COPYING').each_line {|line| lines << line }
lines.take(3)
# =>
# ["{日本語}[rdoc-ref:COPYING.ja]\n",
#  "\n",
#  "Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.\n"]

The lines are read using IO.foreach, all arguments and options are passed to that method; see details at IO.foreach.

With no block given, returns a new Enumerator.

Returns whether the entry represented by self exists and is empty:

dir_pn = Pathname('example_dir')
dir_pn.empty?  # => false  # Dir does not exist.
dir_pn.mkdir
dir_pn.empty?  # => true   # Dir exists and is empty.

file_pn = Pathname('example_dir/example.txt')
file_pn.empty? # => false  # File does not exist.
file_pn.write('')
file_pn.empty? # => true   # File exists and is empty.
dir_pn.empty?  # => false  # Dir exists and is not empty.
file_pn.write('foo')
file_pn.empty? # => false  # File exists and is not empty.

file_pn.delete
dir_pn.delete

Returns an array of pathnames, one for each entry in the directory represented by self:

Pathname('.').entries.take(5)
# =>
# [#<Pathname:.>,
#  #<Pathname:..>,
#  #<Pathname:gc.rb>,
#  #<Pathname:yjit.rb>,
#  #<Pathname:iseq.h>]

Returns whether the entry represented by self is executable; calls FileTest.executable? with argument self.to_s:

Pathname('bin/gem').executable?   # => true
Pathname('README.md').executable? # => false

Returns whether the entry represented by self is executable by the real user and group id of the current process; calls FileTest.executable_real? with argument self.to_s:

pn = Pathname('example')
pn.write('')
pn.executable_real? # => false
pn.chmod(0100)
pn.executable_real? # => true

Returns whether the entry represented by self exists:

Pathname('.').exist?         # => true
Pathname('README.md').exist? # => true
Pathname('nosuch').exist?    # => false

Returns a new pathname containing the absolute path for self.

Evaluates a relative path with respect to the directory given by dirpath:

Dir.chdir('/snap')
# Default dirpath.
Pathname('README').expand_path                  # => #<Pathname:/snap/README>
Pathname('bin').expand_path                     # => #<Pathname:/snap/bin>
Pathname('bin/../var').expand_path              # => #<Pathname:/snap/var>  # Cleaned.
# Other dirpath.
Pathname('../zip').expand_path('/usr/bin/ruby') # => #<Pathname:/usr/bin/zip>
Dir.chdir('/usr/bin')
Pathname('../../snap').expand_path(__FILE__)    # => #<Pathname:/usr/snap>

Evaluates an absolute path without respect to dirpath:

Pathname('/snap').expand_path                       # => #<Pathname:/snap>
Pathname('/snap').expand_path.expand_path('nosuch') # => #<Pathname:/snap>
Pathname('/snap/../snap').expand_path               # => #<Pathname:/snap>  # Cleaned.

More examples:

Dir.chdir('/usr/bin')
Pathname('../../snap').expand_path(__FILE__) # => #<Pathname:/usr/snap>
Pathname('../../snap').expand_path           # => #<Pathname:/snap>

Returns the filename extension of self – usually the portion of the string path beginning from the last period:

Pathname('t.rb').extname               # => ".rb"
Pathname('foo.bar.t.rb').extname       # => ".rb"
Pathname('foo/bar/t.rb').extname       # => ".rb"
Pathname('nosuch.txt').extname         # => ".txt"  # Path need not exist.

Returns the entire string when there is no period:

Pathname('foo').extname # => ""

Returns an empty string when the only period is the first character:

Pathname('.irbrc').extname # => ""

Returns an empty string or '.' when path ends with a period:

Pathname('foo.').extname    # => ""   # On Windows.
Pathname('foo.').extname    # => "."  # Elsewhere.
Pathname('foo....').extname # => ""   # On Windows.
Pathname('foo....').extname # => "."  # Elsewhere.

Returns whether the entry at the path in self exists and is a regular file:

Pathname('README.md').file? # => true
Pathname('lib/').file?      # => false
Pathname('nosuch').file?    # => false

With a block given, performs a depth-first traversal of the path in self; calls the block with each found path:

paths = []
Pathname('lib').find {|path| paths << path }
paths.size  # => 909
paths.take(3)
# =>
# [#<Pathname:lib>,
#  #<Pathname:lib/English.gemspec>,
#  #<Pathname:lib/English.rb>]

When self contains '.', the found paths omit the leading './':

paths = []
Dir.chdir('lib') do
  Pathname('.').find {|path| paths << path }
end
paths.take(3)
# # =>
# [#<Pathname:.>,
#  #<Pathname:English.gemspec>,
#  #<Pathname:English.rb>]

This method calls method Find.find; therefore method Find.prune may be used in the block:

files = []
Pathname('.').find do |path|
  Find.prune if File.basename(path) == 'test'
  next unless File.file?(path) && File.extname(path) == '.rb'
  files << path
end
files.size # => 6690
files.take(3)
# # =>
# [#<Pathname:KNOWNBUGS.rb>,
#  #<Pathname:array.rb>,
#  #<Pathname:ast.rb>]

Raises an exception if the path in self cannot be read.

When keyword argument ignore_error is given as true (the default), certain exceptions during traversal are ignored (i.e., silently rescued): Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::EINVAL; when given as false, no exceptions are rescued.

Note that these exceptions may be ignored only in Pathname#find traversal code; an exception raised before traversal begins, or raised while in the block is not ignored. Each of the calls below raises an Errno::ENOENT exception that is not ignored:

Pathname('nosuch').find { }
Pathname('lib').find {|entry| raise Errno::ENOENT }

With no block given, returns a new Enumerator.

Returns whether string pattern matches against the string path in self, under the control of the given flags; see Filename Matching.

Same as fnmatch.

Freezes self, preventing further modifications; see Frozen Objects.

Returns the string type of the object at the path in self:

Pathname('README.md').ftype   # => "file"
Pathname('lib').ftype         # => "directory"
Pathname('/dev/null').ftype   # => "characterSpecial"
Pathname('/dev/loop0').ftype  # => "blockSpecial"

File.mkfifo('/tmp/pipe', 0666)
Pathname('/tmp/pipe').ftype   # => "fifo"

File.symlink('lib', 'lib_link')
Pathname('lib_link').ftype    # => "link"

require 'socket'
UNIXServer.new('/tmp/socket')
Pathname('/tmp/socket').ftype # => "socket"

Returns 'unknown' if the type cannot be determined.

Returns or yields Pathname objects.

Pathname("ruby-2.4.2").glob("R*.md")
#=> [#<Pathname:ruby-2.4.2/README.md>, #<Pathname:ruby-2.4.2/README.ja.md>]

See Dir.glob. This method uses the base keyword argument of Dir.glob.

Returns whether the filesystem entry for the path stored in self exists, and the effective group id of the calling process is the owner of the entry:

Pathname('README.md').grpowned?   # => true
Pathname('lib').grpowned?         # => true
Pathname('/etc/passwd').grpowned? # => false
Pathname('nosuch').grpowned?      # => false

Returns false on Windows.

Joins the string-converted given objects to the string path in self; returns a new pathname containing the joined string:

Pathname('foo').join                  # => #<Pathname:foo>
Pathname('foo').join('bar')           # => #<Pathname:foo/bar>
Pathname('foo').join('bar', 'baz')    # => #<Pathname:foo/bar/baz>
Pathname('foo').join(Pathname('bar')) # => #<Pathname:foo/bar>

Not supported on some platforms (raises Errno::ENOTSUP).

When supported: like Pathname::chmod, but does not follow symbolic links, and therefore changes the mode of the entry specified by self:

File.write('t.tmp', '')
File.symlink('t.tmp', 'link')
File.stat('t.tmp').mode.to_s(8) # => "100664"
File.stat('link').mode.to_s(8)  # => "100664"
Pathname('link').lchmod(0777)
File.stat('t.tmp').mode.to_s(8) # => "100664"
File.stat('link').mode.to_s(8)  # => "100777"
File.delete('t.tmp')
File.delete('link')

Not supported on some platforms (raises exception).

Calling process must have superuser privileges.

When supported: like Pathname#chown, but does not follow symbolic links, and therefore changes the ownership of the entry at the path in self:

# Super user; all privileges.
Process.uid # => 0
Process.gid # => 0
# Create regular file and symbolic link to it.
File.write('t.tmp', '')
File.symlink('t.tmp', 'link')
# Capture original statuses.
fstat0 = File.stat('t.tmp')  # Method ::stat; status of file.
lstat0 = File.lstat('link')  # Method ::lstat; status of link.
# Original user ids and group ids.
fstat0.uid # => 0
fstat0.gid # => 0
lstat0.uid # => 0
lstat0.gid # => 0
# Change ids for link.
Pathname('link').lchown(1000, 1000)
# Capture new statuses.
fstat1 = File.stat('t.tmp')
lstat1 = File.lstat('link')
# User id and group id for file not changed.
fstat1.uid # => 0
fstat1.gid # => 0
# User id and group id for link changed.
p lstat1.uid # => 1000
p lstat1.gid # => 1000
# Clean up.
File.delete('t.tmp')
File.delete('link')

Returns a File::Stat object for the path in self; does not follow symbolic links, and therefore returns the stat object for that path, regardless of whether it is a symbolic link:

File.write('t.tmp', '')
sleep(1)
File.symlink('t.tmp', 'link')
pn = Pathname('link')
# => #<Pathname:link>
# Method stat: follows link to 't.tmp'.
pn.stat.ctime  # => 2026-06-13 15:02:46.562620885 -0500
# Method lstat; does not follow link.
pn.lstat.ctime # => 2026-06-13 15:02:47.563619647 -0500
File.delete('t.tmp')
File.delete('link')

Like Pathname#utime, but does not follow symbolic links, and therefore changes the times of the entry in self, regardless of whether it is a symbolic link:

# Create a file and a link to it.
file_path = 't.tmp'
link_path = 'link'
File.write(file_path, '')
File.symlink(file_path, link_path)
# Take snapshots of both.
file_stat = File.stat(file_path)
link_stat = File.lstat(link_path)
# Fetch access times and modification times of both.
file_stat.atime # => 2026-06-15 11:03:29.600373255 -0500
file_stat.mtime # => 2026-06-15 11:03:22.247352211 -0500
link_stat.atime # => 2026-06-15 11:03:29.251372254 -0500
link_stat.mtime # => 2026-06-15 11:03:26.66436484 -0500
# Update access time and modification time of the link.
pn = Pathname(link_path)
time = Time.now # => 2026-06-15 11:08:07.384287523 -0500
pn.lutime(time, time)
# Take fresh snapshots of both.
file_stat = File.stat(file_path)
link_stat = File.lstat(link_path)
# Fetch access time and modification time of file (not changed).
file_stat.atime # => 2026-06-15 11:03:29.600373255 -0500
file_stat.mtime # => 2026-06-15 11:03:22.247352211 -0500
# Fetch access time and modification time of link (changed).
link_stat.atime # => 2026-06-15 11:08:29.847301399 -0500
link_stat.mtime # => 2026-06-15 11:08:07.384287523 -0500
# Clean up.
File.delete(file_path)
File.delete(link_path)

Arguments atime and mtime may be Time objects (as above).

Either or both may be integers; when an integer i is passed, Time.new(i) is used.

Either or both may be nil, in which case Time.now is used.

See File System Timestamps.

Not available on some systems.

Creates a new entry at the path in self for the existing entry at path using a hard link:

File.write('doc/t.tmp', 'foo')
Pathname('lib/u.tmp').make_link('doc/t.tmp')
File.read('lib/u.tmp') # => "foo"
File.write('lib/u.tmp', 'bar')
File.read('doc/t.tmp') # => "bar"
File.delete('doc/t.tmp')
File.read('lib/u.tmp') # => "bar"
File.delete('lib/u.tmp')

Raises an exception if the entry at the path in self exists.

Creates a symbolic link at the path in self to the entry at path:

# Create Pathnames.
file_pn = Pathname('doc/extension.rdoc') # => #<Pathname:doc/extension.rdoc>
target_pn = Pathname('..').join(file_pn) # => #<Pathname:../doc/extension.rdoc>
link_pn = Pathname('lib/u.tmp')          # => #<Pathname:lib/u.tmp>
# Create link and verify.
link_pn.make_symlink(target_pn)
file_pn.read == link_pn.read             # => true
link_pn.delete                           # Clean up.

See also: read, readlink, symlink?.

Creates a directory in the underlying file system at the path in self, with the given permissions; see File Permissions:

Dir.mkdir('foo')
File.stat(Dir.new('foo')).mode.to_s(8) # => "40775"
Dir.mkdir('bar', 0644)
File.stat(Dir.new('bar')).mode.to_s(8) # => "40644"
Dir.rmdir('foo')
Dir.rmdir('bar')

Argument permissions is ignored on Windows.

Creates a directory at the path in self; creates intermediate directories as needed:

pn = Pathname('foo/bar/baz')
pn.directory? # => false
pn.mkpath     # Creates directories 'foo', 'foo/bar', 'foo/bar/baz'.
pn.directory? # => true
pn.rmtree     # Clean up.

When mode is given, directories are created with those permissions; see File Permissions. The permissions for already-existing directories are not changed.

Returns whether entry at the path in self is a mountpoint:

Pathname('/').mountpoint?      # => true
Pathname('/etc').mountpoint?   # => false
Pathname('nosuch').mountpoint? # => false

Returns a Time object containing the time of the most recent modification to the entry represented by self; see File System Timestamps:

# A directory and its Pathname.
dir_path = 'doc/foo'
dir_pn = Pathname(dir_path)
# Create directory; directory mtime established.
dir_pn.mkdir
dir_pn.mtime  # => 2026-06-28 16:38:02.675780521 -0500
# A file therein and its Pathname.
file_path = dir_pn.join('t.tmp')
file_pn = Pathname(file_path)
# Create file; file mtime established; directory mtime updated.
file_pn.write('foo')
dir_pn.mtime  # => 2026-06-28 16:41:23.107750483 -0500
file_pn.mtime # => 2026-06-28 16:41:23.107750483 -0500
# Modify file; file mtime updated; directory mtime unchanged.
file_pn.write('bar')
dir_pn.mtime  # => 2026-06-28 16:41:23.107750483 -0500
file_pn.mtime # => 2026-06-28 16:42:48.869163049 -0500
# Clean up.
dir_pn.rmtree

Creates a File object for the entry at the path in self and opens the file; see File.new for details.

With a block given, calls the block with the file; closes the file on block exit:

Pathname('README.md').open {|file| file.size } # => 3469

With no block given, returns the file:

file = Pathname('README.md').open # => #<File:README.md>
file.size                         # => 3469
file.close

Creates a Dir object dir for the directory at the path represented by self; opens dir.

With a block given, calls the block with dir; on block exit, closes dir and returns the block’s return value:

pn = Pathname('.')
pn.opendir {|dir| dir.entries.take(3) }
# => ["README.md", "html", ".git"]

With no block given, returns the open directory dir:

dir = pn.opendir    # => #<Dir:.>
dir.entries.take(3) # => ["README.md", "html", ".git"]
dir.close

Returns whether the entry at the path represented by self exists and is owned by the user of the current process:

pn = Pathname('doc/t.tmp')
pn.write('foo')
pn.owned?               # => true
pn.delete
pn = Pathname('doc/tmp')
pn.mkdir
pn.owned?               # => true
pn.rmdir
Pathname('/etc').owned? # => false

Returns a new pathname representing the parent directory of the entry represented by self:

pn = Pathname('/etc/passwd') # => #<Pathname:/etc/passwd>
pn.parent                    # => #<Pathname:/etc>

Returns whether entry at the path in self is a pipe:

path = '/tmp/foo'
File.mkfifo(path)
pn = Pathname(path) # => #<Pathname:/tmp/foo>
pn.pipe?            # => true
Pathname('.').pipe? # => false
pn.delete           # Clean up.

Reads and returns some or all of the content of the file whose path is self.to_s.

With no arguments given, reads in text mode and returns the entire content of the file:

Pathname.new('t.txt').read
# => "First line\nSecond line\n\nFourth line\nFifth line\n"
Pathname.new('t.ja').read
# => "こんにちは"
Pathname.new('t.dat').read
# => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"

On Windows, text mode can terminate reading and leave bytes in the file unread when encountering certain special bytes. Consider using binread if all bytes in the file should be read.

With argument length given, returns length bytes if available:

Pathname.new('t.txt').read(7)
# => "First l"
Pathname.new('t.ja').read(7)
# => "\xE3\x81\x93\xE3\x82\x93\xE3"
Pathname.new('t.dat').read(7)
# => "\xFE\xFF\x99\x90\x99\x91\x99"

Returns all bytes if length is larger than the files size:

Pathname.new('t.txt').read(700)
# => "First line\r\nSecond line\r\n\r\nFourth line\r\nFifth line\r\n"
Pathname.new('t.ja').read(700)
# => "\xE3\x81\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1\xE3\x81\xAF"
Pathname.new('t.dat').read(700)
# => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"

With arguments length and offset given, returns length bytes if available, beginning at the given offset:

Pathname.new('t.txt').read(10, 2)
# => "rst line\r\n"
Pathname.new('t.ja').read(10, 2)
# => "\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1"
Pathname.new('t.dat').read(10, 2)
# => "\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"

Returns nil if offset is past the end of the file:

Pathname.new('t.txt').read(10, 200) # => nil

Optional keyword arguments opts specify:

• Open Options.

• Encoding options.

Returns whether the entry at the path in self is readable by the owner and group of the current process:

pn = Pathname('/tmp/secret.txt')
pn.write('foo')
pn.readable?                 # => true
pn.chmod(0o000)
pn.readable?                 # => false
pn.delete                    # Clean up.
Pathname('nosuch').readable? # => false

Like readable?, but checks against the real user and group ids instead of the effective ids.

Returns an array of all lines read from the source at the path in self, which must be the path to a file.

Examples here use a file defined at IO Example Files.

With no arguments given, parses lines from the file at the given path, as determined by the default line separator, and returns those lines in an array:

pn = Pathname('t.txt')
ppn.readlines
# => ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]

With argument sep given, parses lines as determined by that line separator (see IO Line Separator):

pn.readlines('li')
# => ["First li", "ne\nSecond li", "ne\n\nFourth li", "ne\nFifth li", "ne\n"]
pn.readlines('')  # Special "paragraphs" separator value.
# => ["First line\nSecond line\n\n", "Fourth line\nFifth line\n"]
pn.readlines(nil) # Special "slurp" separator value.
# => ["First line\nSecond line\n\nFourth line\nFifth line\n"]

With argument limit given, parses lines as determined by the default line separator and the given line-length limit (see IO Line Separator and IO Line Limit):

pn.readlines(7)
# => ["First l", "ine\n", "Second ", "line\n", "\n", "Fourth ", "line\n", "Fifth l", "ine\n"]

With arguments sep and limit given, combines the two behaviors (see IO Line Separator and Line Limit).

Optional keyword arguments options specify:

• IO Open Options.

• Encoding options.

• IO Line Input Options.

Returns a new pathname containing the path to the entry represented by self:

# Create Pathnames.
file_pn = Pathname('doc/extension.rdoc') # => #<Pathname:doc/extension.rdoc>
target_pn = Pathname('..').join(file_pn) # => #<Pathname:../doc/extension.rdoc>
link_pn = Pathname('lib/u.tmp')          # => #<Pathname:lib/u.tmp>
link_pn.make_symlink(target_pn)
link_pn.readlink                         # => #<Pathname:../doc/extension.rdoc>
link_pn.delete

Returns a new pathname containing the real (absolute) pathname of the path in self; the new path is the path in the actual filesystem, and does not contain useless dot-entries ('.' or '..') or symbolic links:

Pathname('/etc/./passwd/../../var').realdirpath
# => #<Pathname:/var>

Only the last component of the new path may be nonexistent:

Pathname('/etc/./passwd/../../var/nosuch').realdirpath
# => #<Pathname:/var/nosuch>
Pathname('/etc/./passwd/../../var/nosuch/nosuch').realdirpath
# Raises Errno::ENOENT: No such file or directory.

Method realpath is similar, but requires all components to exist.

Returns a new pathname containing the real (absolute) pathname of the path in self; the new path is the path in the actual filesystem, and does not contain useless dot-entries ('.' or '..') or symbolic links:

Pathname('/etc/./passwd/../../var').realpath
# => #<Pathname:/var>

All components of the new path must exist:

Pathname('/etc/./passwd/../../var/nosuch').realpath
# Raises Errno::ENOENT: No such file or directory.

Method realdirpath is similar, but does not require the last component to exist.

Returns whether self contains a relative path:

Pathname('lib').relative?   # => true
Pathname('/home').relative? # => false

The result is OS-dependent for some paths:

Pathname('C:/').relative?   # => false # On Windows.
Pathname('C:/').relative?   # => true  # Elsewhere.

Returns a pathname containing the relative filesystem path from the given source to the path in self; source must be a directory path or a pathname containing a directory path:

Pathname('.').relative_path_from('doc/language')   # => #<Pathname:../..>
Pathname('doc/language').relative_path_from('.')   # => #<Pathname:doc/language>
Pathname('doc').relative_path_from('doc/language') # => #<Pathname:..>

The paths need not exist:

Pathname('nosuch').relative_path_from('nosuch/foo/bar/baz')
# => #<Pathname:../../..>

The two paths must be either both absolute or both relative:

Pathname('/var').relative_path_from('/etc') # => #<Pathname:../var>
Pathname('/var').relative_path_from('doc')  # Raises ArgumentError
Pathname('doc').relative_path_from('/etc')  # Raises ArgumentError

Raises an exception if there is no such relative path:

Pathname('foo').relative_path_from('..')    # Raises ArgumentError

Renames the entry at the path in self to the entry given in new_name, which may be either a path or another pathname:

# Create source and destination pathnames and directories.
pn_srcdir = Pathname('/tmp/src')     # => #<Pathname:/tmp/src>
pn_srcdir.mkdir
pn_dstdir = Pathname('/tmp/dst')     # => #<Pathname:/tmp/dst>
pn_dstdir.mkdir
# Create source file pathname and file.
pn_srcfile = pn_srcdir.join('t.tmp') # => #<Pathname:/tmp/src/t.tmp>
pn_srcfile.write('foo')
# Create destination file pathname.
pn_dstfile = pn_dstdir.join('u.tmp') # => #<Pathname:/tmp/dst/u.tmp>
# Rename source file as destination file.
pn_srcfile.rename(pn_dstfile)
pn_srcfile.exist?                    # => false
pn_dstfile.exist?                    # => true

Works for directories, too:

pn_dstdir.rename('/tmp/foo')
pn_dstdir.exist?            # => false
Pathname('/tmp/foo').exist? # => true

Clean up.

pn_srcdir.rmtree
Pathname('/tmp/foo').rmtree

Raises SystemCallError if the entry cannot be renamed.

Deletes the directory at the path in self; returns 0:

pn = Pathname('doc/foo')
pn.mkdir
pn.rmdir

Raises an exception if the entry at the path in self is not a directory, or if the directory is not empty.

Use method rmtree to delete the entire filetree at the path.

Deletes the entire filetree at the path in self; returns 0:

dir_pn = Pathname('foo/bar/baz') # => #<Pathname:foo/bar/baz>
dir_pn.mkpath                    # Create 'baz' and intermediate directories.
file_pn = dir_pn.join('t.tmp')   # => #<Pathname:foo/bar/baz/t.tmp>
file_pn.write('foo')             # Create file at nested directory 'baz'.
Pathname('foo').rmtree           # Delete the entire tree at directory 'foo'.
Pathname('foo').exist?           # => false

Use method rmdir to delete a single (empty) directory.

Returns whether the path in self points to a root directory.

On a non-Windows system, a root directory path is one whose name begins with one or more slash characters (‘’/‘):

Pathname('/').root?       # => true
Pathname('////').root?    # => true
Pathname('/usr').root?    # => false
Pathname('foo').root?     # => false

Does not resolve dot directories:

Pathname('/usr/.').root?  # => false
Pathname('/usr/..').root? # => false

On a Windows system, a root directory path is one whose name begins as above, or with a device letter followed by a colon character (':') and one or more slash characters (‘’/‘):

Pathname('/').root?      # => true
Pathname('////').root?   # => true
Pathname('C:/').root?    # => true
Pathname('C:////').root? # => true
Pathname('c:/').root?    # => true
Pathname('H:/').root?    # => true
Pathname('C:/m').root?   # => false
Pathname('C:').root?     # => false

Returns whether the setgid bit is set in the permissions for the entry at the path in self:

# Create a file and get its permissions and setgid? setting.
pn = Pathname('doc/t.tmp')
pn.write('foo')
mode = pn.stat.mode.to_s(8) # => "100664"
pn.setgid?                  # => false
# Set the bit.
pn.chmod(0o2644)
mode = pn.stat.mode.to_s(8) # => "102644"
pn.setgid?                  # => true
pn.delete                   # Clean up.

On Windows, the bit is never set; the method always returns false.

Returns whether the setuid bit is set in the permissions for the entry at the path in self:

# Create a file and get its permissions and setuid? setting.
pn = Pathname('doc/t.tmp')
pn.write('foo')
mode = pn.stat.mode.to_s(8) # => "100664"
pn.setuid?                  # => false
# Set the bit.
pn.chmod(0o4644)
mode = pn.stat.mode.to_s(8) # => "104644"
pn.setuid?                  # => true
pn.delete                   # Clean up.

On Windows, the bit is never set; the method always returns false.

Returns the size of the entry at the path in self:

Pathname('README.md').size # => 3469
Pathname('doc').size       # => 4096
pn = Pathname('doc/t.tmp')
pn.write('')
pn.size                    # => 0
pd.delete                  # Clean up.

Raises an exception if the entry does not exist.

If the file or directory entry at the path in self exists, returns its size if non-zero, or nil if zero:

pn = Pathname('doc/t.tmp')
pn.write('foo')
pn.size? # => 3
pn.write('')
pn.size? # => nil

Returns nil if the entry does not exist:

pn.delete
pn.size? # => nil

Returns whether entry at the path in self is a socket:

require 'socket'
path = 'doc/socket'
server = UNIXServer.new(path) # => #<UNIXServer:doc/socket>
pn = Pathname(path)           # => #<Pathname:doc/socket>
pn.socket?                    # => true
server.close
pn.unlink
Pathname('README.md').socket? # => false
Pathname('nosuch').socket?    # => false

Returns false on Windows.

Returns a 2-element array containing dirname and basename:

Pathname('lib/pathname.rb').split # => [#<Pathname:lib>, #<Pathname:pathname.rb>]
Pathname('README.md').split       # => [#<Pathname:.>, #<Pathname:README.md>]
Pathname('').split                # => [#<Pathname:.>, #<Pathname:>]
Pathname('nosuch/foo/bar').split  # => [#<Pathname:nosuch/foo>, #<Pathname:bar>]

Returns a File::Stat object for the entry at the path in self:

Pathname('README.md').stat.inspect
=> "#<File::Stat dev=0x10302, ino=22941341, mode=0100664, nlink=1, uid=1000, gid=1000, rdev=0x0, size=3469, blksize=4096, blocks=8, atime=2026-07-10 15:24:17.476506084 -0500, mtime=2026-07-07 10:23:27.320088262 -0500, ctime=2026-07-07 10:23:27.320088262 -0500>"
Pathname('doc').stat.inspect
=> "#<File::Stat dev=0x10302, ino=22941930, mode=040775, nlink=22, uid=1000, gid=1000, rdev=0x0, size=4096, blksize=4096, blocks=8, atime=2026-07-11 10:05:20.480330738 -0500, mtime=2026-07-11 10:05:06.34333645 -0500, ctime=2026-07-11 10:05:06.34333645 -0500>"

Returns whether the sticky bit is set for the entry at the path in self:

pn = Pathname('t.tmp')
pn.write('foo')
pn.stat.mode.to_s(8) # => "100664"
pn.sticky?           # => false
pn.chmod(0o1644)
pn.stat.mode.to_s(8) # => "101644"
pn.sticky?           # => true
pn.delete

Returns false on Windows.

Returns a new pathname whose path is the path in self, after the specified substitutions.

Argument pattern may be a string or a Regexp; argument replacement may be a string or a hash.

Varying types for the argument values makes this method very versatile.

Below are some simple examples; for many more related examples (using strings, not pathnames), see Substitution Methods.

With arguments pattern and string replacement given, replaces the first matching substring with the given replacement string:

pn = Pathname('abracadabra.txt') # => #<Pathname:abracadabra.txt>
pn.sub('bra', 'xyzzy')           # => #<Pathname:axyzzycadabra.txt>
pn.sub(/bra/, 'xyzzy')           # => #<Pathname:axyzzycadabra.txt>
pn.sub('nope', 'xyzzy')          # => #<Pathname:abracadabra.txt>

With arguments pattern and hash replacement given, replaces the first matching substring with a value from the given replacement hash, or removes it:

h = {'a' => 'A', 'b' => 'B', 'c' => 'C'}
pn.sub('b', h) # => #<Pathname:aBracadabra.txt>
pn.sub(/b/, h) # => #<Pathname:aBracadabra.txt>
pn.sub(/d/, h) # => #<Pathname:abracaabra.txt>  # 'd' removed.

With argument pattern and a block given, calls the block with the first matching substring; replaces that substring with the block’s return value:

pn.sub('b') {|match| match.upcase } # => #<Pathname:aBracadabra.txt>
pn.sub(/X/) {|match| match.upcase } # => #<Pathname:abracadabra.txt>

Returns a new pathname whose path is the path in self, after specified changes:

Pathname('t.tmp').sub_ext('.txt') # => #<Pathname:t.txt>     # Extension replaced.
Pathname('temp').sub_ext('.txt')  # => #<Pathname:temp.txt>  # Extension added.
Pathname('t.tmp').sub_ext('')     # => #<Pathname:t>         # Extension removed.

Returns whether the entry at the path in self is a symbolic link:

# Create Pathnames.
file_pn = Pathname('doc/extension.rdoc') # => #<Pathname:doc/extension.rdoc>
target_pn = Pathname('..').join(file_pn) # => #<Pathname:../doc/extension.rdoc>
link_pn = Pathname('lib/u.tmp')          # => #<Pathname:lib/u.tmp>
link_pn.symlink?                         # => false
# Create link.
link_pn.make_symlink(target_pn)
link_pn.symlink?                         # => true
link_pn.delete                           # Clean up.

Opens the file at the path in self with the given mode and permissions; returns the integer file descriptor.

If the file is to be readable, it must exist; if the file is to be writable and does not exist, it is created with the given permissions:

pn = Pathname('doc/t.tmp')
pn.write('foo')
fd = pn.sysopen             # => 5
IO.new(fd).close
fd = pn.sysopen('w')        # => 5
IO.new(fd).close
fd = pn.sysopen('r', 0o644) # => 5
IO.new(fd).close
pn.delete

Returns a copy of the string path in self:

Pathname('nosuch/foo/bar').to_s # => "nosuch/foo/bar"

Adjusts the size of file at the path in self to the given size; returns 0:

pn.write('0123456789')
pn.size # => 10
pn.truncate(5)
pn.size # => 5
pn.read # => "01234"

Pads on the right with null characters if necessary:

pn.truncate(10)
pn.size # => 10
pn.read # => "01234\u0000\u0000\u0000\u0000\u0000"

Removes the entry represented by self; returns 0 if a directory, 1 if a file:

Pathname(Pathname.mktmpdir).unlink # => 0
Pathname(Tempfile.create).unlink   # => 1

For the entry at the path in self, updates its access time to the given atime and its modification time to the given mtime; each given time may be a Time object, an integer representing a time, or nil (meaning Time.now):

pn = Pathname('doc/t.tmp')
pn.write('foo')
pn.stat.atime   # => 1969-12-31 18:00:00 -0600
pn.stat.mtime   # => 2026-07-11 16:12:15.832556524 -0500
pn.utime(0, 0)
pn.stat.atime   # => 1969-12-31 18:00:00 -0600
pn.stat.mtime   # => 1969-12-31 18:00:00 -0600
pn.utime(nil, nil)
pn.stat.atime   # => 2026-07-11 16:13:06.982646673 -0500
pn.stat.mtime   # => 2026-07-11 16:13:04.983530291 -0500
time = Time.now # => 2026-07-11 16:13:40.190110708 -0500
pn.utime(time, time)
pn.stat.atime   # => 2026-07-11 16:13:51.99317823 -0500
pn.stat.mtime   # => 2026-07-11 16:13:40.190110708 -0500