Re: Subject: Manual directory stack ambiguity

[Tim Nielens]

The commands work fine, and one understands pretty easily while playing with them how the stack works.

There are just ambiguities in the manual.

Check the pushd builtin command documentation.

"
`pushd'
          pushd [-n] [+N | -N | DIR]

     Save the current directory on the top of the directory stack and
     then `cd' to DIR.  With no arguments, `pushd' exchanges the top
     two directories.

"

The first sentence implies that the current directory is not part of what the manual calls the "directory stack". The current directory is pushed on the stack and then the command cds to DIR (which will not be part of the stack).

The second sentence says that the top two directories are exchanged with no arguments, but in practice it's the current dir and the top stack directory that are exchanged if we accept what they define as stack in the first sentence. In that perspective, the second sentence should be rewritten something like : "With no arguments, pushd exchanges the top stack directory with the current directory and cds to the old top directory".

It's details, but I think the manual should state whether the stack includes the cd and correct those little ambiguities. What does it refer to when it uses terms like "top directory of the stack".. Is is the current dir or the last pushed directory ?

2015-08-16 13:51 GMT+02:00 Chet Ramey <chet.ramey@case.edu>:

On 8/14/15 6:08 AM, Tim Nielens wrote:

> Bash Version: 4.3
> Patch Level: 39
> Release Status: release
>
> Description:
> There is a ambiguity about the directory stack in the manual: 6.8.1
> Directory Stack Builtins
>
> It's difficult to understand if the current directory is part of the stack
> or not.

`dirs' always displays the directory stack, and the current directory is
always the first element (sometimes the only one).

The current directory is always the implicit top of the directory stack,
so things like popd and pushd without arguments can use it, so `dirs' lists
it as the first element.

When you use pushd for the first time, for instance, you push the directory
given as an argument `on top' of the current directory, and make it the
new current directory, so it's the top of the stack for a subsequent pushd
or popd.

If you haven't pushed anything, there's nothing to pop, and `popd' returns
an error message.  If you have pushed something, you pop the current
directory and return to the immediately previous one.

pushd always changes the current directory unless the -n option is given.
Since the `topmost' element of the stack is always the current directory,
popd will change the current directory if it operates on the top element
(popd, popd +0), unless the -n option is given.

Since a successful `pushd' or `popd' always prints the contents of the
directory stack, there should not be too much confusion about its members.

--
``The lyf so short, the craft so long to lerne.'' - Chaucer
                 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, ITS, CWRU    chet@case.edu    http://cnswww.cns.cwru.edu/~chet/