The cd built-in changes the working directory.

Syntax

  • cd [-L|-P [-e]] [directory]

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 PWD variable, whose previous value is again assigned to the OLDPWD variable. The new PWD value will not contain any . or .. components except when the shell is in the POSIXly-correct mode and the new pathname begins with /...

If directory is a relative path that does not start with ‘.’ or ‘..’, paths in the CDPATH variable are searched to find a new working directory. The search is done in a manner similar to the last step of 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 YASH_AFTER_CD variable is executed as a command unless the shell is in the POSIXly-correct mode. If the variable is an array, its values are executed iteratively (cf. eval built-in).

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

directory

The pathname of the new working directory.

If directory is a single hyphen (‘-’), the value of the 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 home directory.

Exit status

  • If the working directory is successfully changed:

    • If the -L option is effective, the exit status is 0.

    • If the -P option is effective:

      • If the absolute pathname of the new working directory is successfully obtained, the exit status is 0.

      • If the PWD variable cannot be updated because the absolute pathname of the new working directory cannot be obtained:

        • If the -e option is effective, the exit status is 1.

        • If the -e option is not effective, the exit status is 0.

  • 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 HOME or OLDPWD, the exit status is 4.

  • If the command arguments are invalid, the exit status is 5.

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

If the PWD or OLDPWD variable is read-only, the variable is not updated, but that does not affect the exit status.

Notes

The cd built-in is a 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.