No man page for the cd command

Question

Ubuntu Linux 15.10 - I just noticed that there is no man page for cd

This seems a bit strange.

I tried:

man cd

at the cmd line and I get back

No manual entry for cd

I was trying to find documentation on

cd -

which is super-handy for flipping between the last dir and the current dir

and cd --

which seems to be an alias for

cd ~

Am I missing something very obvious here, or should the man page be present?

Answer 1

cd is not a command, it's built into your shell. This is necessary because your current working directory is controlled by the PWD environment variable named after the pwd or "print working directory" command.

The environment variables of a parent process cannot be changed by a child process. So if your shell ran /bin/cd which changed PWD it would only affect /bin/cd and anything it ran. It would not change the shell's PWD.

Some systems, like OS X and CentOS, map the cd man page to builtin which lists all the shell built ins and lets you know you should look at your shell's man page.

You can check what shell you have with echo $SHELL, it's probably bash.

Answer 2

cd is a builtin shell command.

$ type cd
cd is a shell builtin

You can open a help page for cd on Bash with

$ help cd

Which currently shows (Ubuntu 16.04):

$ help cd
cd: cd [-L|[-P [-e]] [-@]] [dir]
    Change the shell working directory.

    Change the current directory to DIR.  The default DIR is the value of the
    HOME shell variable.

    The variable CDPATH defines the search path for the directory containing
    DIR.  Alternative directory names in CDPATH are separated by a colon (:).
    A null directory name is the same as the current directory.  If DIR begins
    with a slash (/), then CDPATH is not used.

    If the directory is not found, and the shell option `cdable_vars' is set,
    the word is assumed to be  a variable name.  If that variable has a value,
    its value is used for DIR.

    Options:
        -L  force symbolic links to be followed: resolve symbolic links in
        DIR after processing instances of `..'
        -P  use the physical directory structure without following symbolic
        links: resolve symbolic links in DIR before processing instances
        of `..'
        -e  if the -P option is supplied, and the current working directory
        cannot be determined successfully, exit with a non-zero status
        -@  on systems that support it, present a file with extended attributes
            as a directory containing the file attributes

    The default is to follow symbolic links, as if `-L' were specified.
    `..' is processed by removing the immediately previous pathname component
    back to a slash or the beginning of DIR.

    Exit Status:
    Returns 0 if the directory is changed, and if $PWD is set successfully when
    -P is used; non-zero otherwise.

Unfortunately, it does not answer your questions. There is documentation that does, however.

You can get to it with

$ man builtins

It opens many pages of help with less, my default viewer. I can find the help for cd by pressing the / key, then typing cd, then Enter, and pressing n twice gets me to the third instance of the substring, and the help, which reads:

   cd [-L|[-P [-e]] [-@]] [dir]
          Change  the  current  directory to dir.  if dir is not supplied,
          the value of the HOME shell variable is the default.  Any  addi‐
          tional arguments following dir are ignored.  The variable CDPATH
          defines the search path for the directory containing  dir:  each
          directory  name  in  CDPATH  is  searched  for dir.  Alternative
          directory names in CDPATH are separated by a colon (:).  A  null
          directory  name  in CDPATH is the same as the current directory,
          i.e., ``.''.  If dir begins with a slash (/), then CDPATH is not
          used.  The  -P  option  causes  cd to use the physical directory
          structure by resolving symbolic links while traversing  dir  and
          before processing instances of .. in dir (see also the -P option
          to the set builtin command); the -L option forces symbolic links
          to  be followed by resolving the link after processing instances
          of .. in dir.  If .. appears in dir, it is processed by removing
          the  immediately previous pathname component from dir, back to a
          slash or the beginning of dir.  If the  -e  option  is  supplied
          with  -P,  and  the current working directory cannot be success‐
          fully determined after a successful directory  change,  cd  will
          return  an unsuccessful status.  On systems that support it, the
          -@ option presents the extended  attributes  associated  with  a
          file  as  a directory.  An argument of - is converted to $OLDPWD
          before the directory change is attempted.  If a non-empty direc‐
          tory  name  from  CDPATH is used, or if - is the first argument,
          and the directory change is successful, the absolute pathname of
          the  new  working  directory  is written to the standard output.
          The return value is  true  if  the  directory  was  successfully
          changed; false otherwise.

Look for the - argument about the seventh line from the end:

An argument of - is converted to $OLDPWD before the directory change is attempted.

Note that there is no -- argument - which seems to mean that it actually ignores it.