Format
- cd [directory]
- cd old new
- cd –
tcsh shell: cd [-p] [-l] [-n|-v] [name]
Description
The command cd directory changes the working directory of the current shell execution environment (see sh) to directory. If you specify directory as an absolute path name, beginning with /, this is the target directory. cd assumes the target directory to be the name just as you specified it. If you specify directory as a relative path name, cd assumes it to be relative to the current working directory.
If the variable CDPATH is defined in the shell, the built-in cd command searches for a relative path name in each of the directories defined in CDPATH. If cd finds the directory outside the working directory, it displays the new working directory.
Use colons to separate directories in CDPATH. In CDPATH, a null string represents the working directory. For example, if the value of CDPATH begins with a separator character, cd searches the working directory first; if it ends with a separator character, cd searches the working directory last.
Calling cd without arguments sets the working directory to the value of the HOME environment variable, if the variable exists. If there is no HOME variable, cd does not change the working directory.
The form cd old new is an extension to the POSIX standard and optionally to the Korn shell. The shell keeps the name of the working directory in the variable PWD. The cd command scans the current value of PWD and replaces the first occurrence of the string old with the string new. The shell displays the resulting value of PWD, and it becomes the new working directory.
If either directory is a symbolic link to another directory, the behavior depends on the setting of the shell's –o logical option. See the set command for more information.
For cd in the tcsh shell, if a directory name is given, cd changes the tcsh shell's working directory to name. If not, it changes the directory to home. If name is '-' it is interpreted as the previous working directory. If name is not a subdirectory of the current directory (and does not begin with /, ./ or ../), each component of the tcsh variable cdpath is checked to see if it has a subdirectory name. Finally, if all else fails but name is a tcsh shell variable whose value begins with /, then this is tried to see if it is a directory (see also the implicitcd tcsh shell variable).
- -l
- Output is expanded explicitly to home or the path name of the home directory for the user.
- -n
- Entries are wrapped before they reach the edge of the screen.
- -p
- Prints the final directory stack.
- -v
- Entries are printed one per line, preceded by their stack positions.
If more than one of -n or -v is given, -v takes precedence. -p is accepted but does nothing.
Environment variables
- CDPATH
- Contains a list of directories for cd to search in when directory is a relative path name.
- HOME
- Contains the name of your home directory. This is used when you do not specify directory on the command line.
- OLDPWD
- Contains the path name of the previous working directory. This is used by cd –.
- PWD
- Contains the path name of the current working directory. This is set by cd after changing to that directory.
Localization
- LANG
- LC_ALL
- LC_CTYPE
- LC_MESSAGES
- NLSPATH
See Localization for more information.
Usage notes
cd is a built-in shell command.
Exit values
- 0
- Successful completion
- 1
- Failure due to any of the following reasons:
- No HOME directory
- No previous directory
- A search for directory failed
- An old-to-new substitution failed
- 2
An incorrect command-line option, or too many arguments
Messages
- dir bad directory
- cd could not locate the target directory. This does not change the working directory.
- Restricted
- You are using the restricted version of the shell (for example, by specifying the –r option for sh). The restricted shell does not allow the cd command.
- No HOME directory
- You did not assign a value to the HOME environment variable. Thus, when you run cd in order to return to your home directory, cd cannot determine what your home directory is.
- No previous directory
- You tried the command cd – to return to your previous directory; but there is no record of your previous directory.
- Pattern old not found in dir
- You tried a command of the form cd old new. However, the name of the working directory dir does not contain any string matching the regular expression old.
Portability
POSIX.2, X/Open Portability Guide.
All UNIX systems feature the first form of the command.
The cd old new form of the command is an extension of the POSIX standard.
Related information
dirs, popd, pushd, set, sh, tcsh