= Cd built-in
:encoding: UTF-8
:lang: en
//:title: Yash manual - Cd built-in

The dfn:[cd built-in] changes the working directory.

[[syntax]]
== Syntax

- +cd [-L|-P [-e]] [{{directory}}]+

[[description]]
== Description

The cd built-in changes the working directory to the directory specified by
the operand.

The pathname of the new working directory is assigned to the
link:params.html#sv-pwd[+PWD+ variable], whose previous value is again
assigned to the link:params.html#sv-oldpwd[+OLDPWD+ variable].
The new +PWD+ value will not contain any +.+ or +..+ components except when
the shell is in the link:posix.html[POSIXly-correct mode] and the new pathname
begins with +/..+.

If {{directory}} is a relative path that does not start with `.' or `..',
paths in the link:params.html#sv-cdpath[+CDPATH+ variable] are searched to
find a new working directory.
The search is done in a manner similar to the last step of
link:exec.html#search[command search], but a directory is sought instead of an
executable regular file.
If a new working directory was found from +CDPATH+, its pathname is printed to
the standard output.
If no applicable directory was found in the search, {{directory}} is simply
treated as a pathname relative to the current working directory.

If the working directory was successfully changed, the value of the
link:params.html#sv-yash_after_cd[+YASH_AFTER_CD+ variable] is executed as a
command unless the shell is in the link:posix.html[POSIXly-correct mode].
If the variable is an link:params.html#arrays[array], its values are executed
iteratively (cf. link:_eval.html#iter[eval built-in]).

[[options]]
== Options

+-L+::
+--logical+::
Symbolic links in the pathname of the new working directory are not resolved.
The new value of the +PWD+ may include pathname components that are symbolic
links.

+-P+::
+--physical+::
Symbolic links in the pathname of the new working directory are resolved.
The new value of the +PWD+ variable never includes pathname components that
are symbolic links.

+-e+::
+--ensure-pwd+::
This option must be specified with +-P+ (+--physical+).
If this option is specified and if the absolute pathname of the new working
directory cannot be obtained after successfully changing the working
directory, the exit status is 1. If this option is not specified, the exit
status is 0 in such a case.

+--default-directory={{directory}}+::
If this option is specified and the {{directory}} operand is omitted, the
argument to this option is used for the {{directory}} operand.
If the {{directory}} operand is specified, this option is ignored.

The +-L+ (+--logical+) and +-P+ (+--physical+) options are mutually exclusive:
only the last specified one is effective.
If neither is specified, +-L+ is assumed.

[[operands]]
== Operands

{{directory}}::
The pathname of the new working directory.
+
If {{directory}} is a single hyphen (`-'), the value of the
link:params.html#sv-oldpwd[+OLDPWD+ variable] is assumed for the new directory
pathname, which is printed to the standard output.
+
If {{directory}} is omitted, the working directory is changed to the directory
specified by the +--default-directory=...+ option. If that option is not
specified either, the default is the link:params.html#sv-home[home directory].

[[exitstatus]]
== Exit status

* If the working directory is successfully changed, the exit status is 0,
except in the following cases the exit status is 1:
** The +PWD+ or +OLDPWD+ variable cannot be updated because the variable is
   read-only.
** The +-P+ and +-e+ options are effective and the +PWD+ variable cannot be
   updated because the absolute pathname of the new working directory cannot
   be obtained.
* If the working directory cannot be changed because of an error in the
  underlying +chdir+ system call, the exit status is 2.
* If the +-L+ option is effective and the new directory pathname cannot be
  canonicalized because of a +..+ component referring to a non-existent
  directory, the exit status is 3.
* If {{directory}} cannot be processed because of an unset or empty
  link:params.html#sv-home[+HOME+] or link:params.html#sv-oldpwd[+OLDPWD+],
  the exit status is 4.
* If the command arguments are invalid or if an empty operand is supplied
  for {{directory}}, the exit status is 5.

If and only if the exit status is 2 or larger, the working directory is not
changed.

[[notes]]
== Notes

The cd built-in is a link:builtin.html#types[mandatory built-in].

The POSIX standard does not define the use of the +YASH_AFTER_CD+ variable or
the +--default-directory=...+ option.

The exit status of the commands in the +YASH_AFTER_CD+ variable does not
affect that of the cd built-in.

// vim: set filetype=asciidoc textwidth=78 expandtab:
