Changes the current working directory to self:
Dir.pwd # => "/" dir = Dir.new('example') dir.chdir Dir.pwd # => "/example"
With a block, temporarily changes the working directory:
Calls the block.
Changes to the given directory.
Executes the block (yields no args).
Restores the previous working directory.
Returns the block’s return value.
Uses Dir.fchdir if available, and Dir.chdir if not, see those methods for caveats.
Changes the current working directory.
With argument new_dirpath and no block, changes to the given dirpath:
Dir.pwd # => "/example" Dir.chdir('..') # => 0 Dir.pwd # => "/"
With no argument and no block:
Changes to the value of environment variable HOME if defined.
Otherwise changes to the value of environment variable LOGDIR if defined.
Otherwise makes no change.
With argument new_dirpath and a block, temporarily changes the working directory:
Calls the block with the argument.
Changes to the given directory.
Executes the block (yielding the new path).
Restores the previous working directory.
Returns the block’s return value.
Example:
Dir.chdir('/var/spool/mail') Dir.pwd # => "/var/spool/mail" Dir.chdir('/tmp') do Dir.pwd # => "/tmp" end Dir.pwd # => "/var/spool/mail"
With no argument and a block, calls the block with the current working directory (string) and returns the block’s return value.
Calls to Dir.chdir with blocks may be nested:
Dir.chdir('/var/spool/mail') Dir.pwd # => "/var/spool/mail" Dir.chdir('/tmp') do Dir.pwd # => "/tmp" Dir.chdir('/usr') do Dir.pwd # => "/usr" end Dir.pwd # => "/tmp" end Dir.pwd # => "/var/spool/mail"
In a multi-threaded program an error is raised if a thread attempts to open a chdir block while another thread has one open, or a call to chdir without a block occurs inside a block passed to chdir (even in the same thread).
Raises an exception if the target directory does not exist.
An object of class Dir represents a directory in the underlying file system.
It consists mainly of:
A string path, given when the object is created, that specifies a directory in the underlying file system; method path returns the path.
A collection of string entry names, each of which is the name of a directory or file in the underlying file system; the entry names may be retrieved in an array-like fashion or in a stream-like fashion.
Some examples on this page use this simple file tree:
example/ ├── config.h ├── lib/ │ ├── song/ │ │ └── karaoke.rb │ └── song.rb └── main.rb
Others use the file tree for the Ruby project itself.
A Dir object is in some ways array-like:
It has instance methods children, each, and each_child.
It includes module Enumerable.
A Dir object is in some ways stream-like.
The stream is initially open for reading, but may be closed manually (using method close), and will be closed on block exit if created by Dir.open called with a block. The closed stream may not be further manipulated, and may not be reopened.
The stream has a position, which is the index of an entry in the directory:
The initial position is zero (before the first entry).
Method pos= sets the position (but ignores a value outside the stream), and returns the position.
Method seek is like pos=, but returns self (convenient for chaining).
Method read, if not at end-of-stream, reads the next entry and increments the position; if at end-of-stream, does not increment the position.
Method rewind sets the position to zero.
Examples (using the simple file tree):
dir = Dir.new('example') # => #<Dir:example> dir.pos # => 0 dir.read # => "." dir.read # => ".." dir.read # => "config.h" dir.read # => "lib" dir.read # => "main.rb" dir.pos # => 5 dir.read # => nil dir.pos # => 5 dir.rewind # => #<Dir:example> dir.pos # => 0 dir.pos = 3 # => 3 dir.pos # => 3 dir.seek(4) # => #<Dir:example> dir.pos # => 4 dir.close # => nil dir.read # Raises IOError.
First, what’s elsewhere. Class Dir:
Inherits from class Object.
Includes module Enumerable, which provides dozens of additional methods.
Here, class Dir provides methods that are useful for:
close: Closes the directory stream for self.
pos=: Sets the position in the directory stream for self.
read: Reads and returns the next entry in the directory stream for self.
rewind: Sets the position in the directory stream for self to the first entry.
seek: Sets the position in the directory stream for self the entry at the given offset.
::chdir: Changes the working directory of the current process to the given directory.
::chroot: Changes the file-system root for the current process to the given directory.
::children: Returns an array of names of the children (both files and directories) of the given directory, but not including . or ...
::empty?: Returns whether the given path is an empty directory.
::entries: Returns an array of names of the children (both files and directories) of the given directory, including . and ...
::exist?: Returns whether the given path is a directory.
::getwd (aliased as pwd): Returns the path to the current working directory.
::glob: Returns an array of file paths matching the given pattern and flags.
::home: Returns the home directory path for a given user or the current user.
children: Returns an array of names of the children (both files and directories) of self, but not including . or ...
fileno: Returns the integer file descriptor for self.
path (aliased as to_path): Returns the path used to create self.
tell (aliased as pos): Returns the integer position in the directory stream for self.
::each_child: Calls the given block with each entry in the given directory, but not including . or ...
::foreach: Calls the given block with each entry in the given directory, including . and ...
each: Calls the given block with each entry in self, including . and ...
each_child: Calls the given block with each entry in self, but not including . or ...
::mkdir: Creates a directory at the given path, with optional permissions.
::new: Returns a new Dir for the given path, with optional encoding.
::open: Same as ::new, but if a block is given, yields the Dir to the block, closing it upon block exit.
::unlink (aliased as ::delete and ::rmdir): Removes the given directory.
inspect: Returns a string description of self.
Changes the current working directory to the directory specified by the integer file descriptor fd.
When passing a file descriptor over a UNIX socket or to a child process, using fchdir instead of chdir avoids the time-of-check to time-of-use vulnerability
With no block, changes to the directory given by fd:
Dir.chdir('/var/spool/mail') Dir.pwd # => "/var/spool/mail" dir = Dir.new('/usr') fd = dir.fileno Dir.fchdir(fd) Dir.pwd # => "/usr"
With a block, temporarily changes the working directory:
Calls the block with the argument.
Changes to the given directory.
Executes the block (yields no args).
Restores the previous working directory.
Returns the block’s return value.
Example:
Dir.chdir('/var/spool/mail') Dir.pwd # => "/var/spool/mail" dir = Dir.new('/tmp') fd = dir.fileno Dir.fchdir(fd) do Dir.pwd # => "/tmp" end Dir.pwd # => "/var/spool/mail"
This method uses the fchdir() function defined by POSIX 2008; the method is not implemented on non-POSIX platforms (raises NotImplementedError).
Raises an exception if the file descriptor is not valid.
In a multi-threaded program an error is raised if a thread attempts to open a chdir block while another thread has one open, or a call to chdir without a block occurs inside a block passed to chdir (even in the same thread).
Creates a directory in the underlying file system at dirpath with the given permissions; returns zero:
Dir.mkdir('foo') File.stat(Dir.new('foo')).mode.to_s(8)[1..4] # => "0755" Dir.mkdir('bar', 0644) File.stat(Dir.new('bar')).mode.to_s(8)[1..4] # => "0644"
See File Permissions. Note that argument permissions is ignored on Windows.
Removes the directory at dirpath from the underlying file system:
Dir.rmdir('foo') # => 0
Raises an exception if the directory is not empty.
Returns the operating system’s temporary file path.
Dir.mktmpdir creates a temporary directory.
The directory is created with 0700 permission. Application should not change the permission to make the temporary directory accessible from other users.
The prefix and suffix of the name of the directory is specified by the optional first argument, prefix_suffix.
If it is not specified or nil, “d” is used as the prefix and no suffix is used.
If it is a string, it is used as the prefix and no suffix is used.
If it is an array, first element is used as the prefix and second element is used as a suffix.
Dir.mktmpdir {|dir| dir is ".../d..." } Dir.mktmpdir("foo") {|dir| dir is ".../foo..." } Dir.mktmpdir(["foo", "bar"]) {|dir| dir is ".../foo...bar" }
The directory is created under Dir.tmpdir or the optional second argument tmpdir if non-nil value is given.
Dir.mktmpdir {|dir| dir is "#{Dir.tmpdir}/d..." } Dir.mktmpdir(nil, "/var/tmp") {|dir| dir is "/var/tmp/d..." }
If a block is given, it is yielded with the path of the directory. The directory and its contents are removed using FileUtils.remove_entry before Dir.mktmpdir returns. The value of the block is returned.
Dir.mktmpdir {|dir| # use the directory... open("#{dir}/foo", "w") { something using the file } }
If a block is not given, The path of the directory is returned. In this case, Dir.mktmpdir doesn’t remove the directory.
dir = Dir.mktmpdir begin # use the directory... open("#{dir}/foo", "w") { something using the file } ensure # remove the directory. FileUtils.remove_entry dir end
Returns the canonicalized absolute path of the directory of the file from which this method is called. It means symlinks in the path is resolved. If __FILE__ is nil, it returns nil. The return value equals to File.dirname(File.realpath(__FILE__)).
The path where gems are to be installed.
Calls the block with each entry name in the directory at dirpath; sets the given encoding onto each passed entry_name:
Dir.foreach('/example') {|entry_name| p entry_name }
Output:
"config.h" "lib" "main.rb" ".." "."
Encoding:
Dir.foreach('/example') {|entry_name| p entry_name.encoding; break } Dir.foreach('/example', encoding: 'US-ASCII') {|entry_name| p entry_name.encoding; break }
Output:
#<Encoding:UTF-8> #<Encoding:US-ASCII>
See String Encoding.
Returns an enumerator if no block is given.
Returns an array of the entry names in the directory at dirpath except for '.' and '..'; sets the given encoding onto each returned entry name:
Dir.children('/example') # => ["config.h", "lib", "main.rb"] Dir.children('/example').first.encoding # => #<Encoding:UTF-8> Dir.children('/example', encoding: 'US-ASCII').first.encoding # => #<Encoding:US-ASCII>
See String Encoding.
Raises an exception if the directory does not exist.
Calls the block with each entry name in self:
Dir.new('example').each {|entry_name| p entry_name }
Output:
"." ".." "config.h" "lib" "main.rb"
With no block given, returns an Enumerator.
Returns an array of the entry names in self except for '.' and '..':
dir = Dir.new('/example') dir.children # => ["config.h", "lib", "main.rb"]
Changes the root directory of the calling process to that specified in dirpath. The new root directory is used for pathnames beginning with '/'. The root directory is inherited by all children of the calling process.
Only a privileged process may call chroot.
See Linux chroot.
Default home directory path to be used if an alternate value is not specified in the environment
Path for gems in the user’s home directory
Recursively removes the directory entry given by path, which should be the entry for a regular file, a symbolic link, or a directory.
Argument path should be interpretable as a path.
Optional argument force specifies whether to ignore raised exceptions of StandardError and its descendants.
Related: methods for deleting.
Recursively removes the directory entry given by path, which should be the entry for a regular file, a symbolic link, or a directory.
Argument path should be interpretable as a path.
Optional argument force specifies whether to ignore raised exceptions of StandardError and its descendants.
Related: methods for deleting.
Sets a target name that the user can then use to configure various “with” options with on the command line by using that name. For example, if the target is set to “foo”, then the user could use the --with-foo-dir=prefix, --with-foo-include=dir and --with-foo-lib=dir command line options to tell where to search for header/library files.
You may pass along additional parameters to specify default values. If one is given it is taken as default prefix, and if two are given they are taken as “include” and “lib” defaults in that order.
In any case, the return value will be an array of determined “include” and “lib” directories, either of which can be nil if no corresponding command line option is given when no default value is specified.
Note that dir_config only adds to the list of places to search for libraries and include files. It does not link the libraries into your application.
SyntaxSuggest.record_dir [Private]
Used to generate a unique directory to record search steps for debugging
Returns an array of the entry names in the directory at dirpath; sets the given encoding onto each returned entry name:
Dir.entries('/example') # => ["config.h", "lib", "main.rb", "..", "."] Dir.entries('/example').first.encoding # => #<Encoding:UTF-8> Dir.entries('/example', encoding: 'US-ASCII').first.encoding # => #<Encoding:US-ASCII>
See String Encoding.
Raises an exception if the directory does not exist.
Returns the file descriptor used in dir.
d = Dir.new('..') d.fileno # => 8
This method uses the dirfd() function defined by POSIX 2008; the method is not implemented on non-POSIX platforms (raises NotImplementedError).