Skip to main content

How to Get the Current Directory Stack Size with %DIRCMD%

The PUSHD and POPD commands are a powerful feature in batch scripting that allow you to "bookmark" a directory, navigate to a new one, and then easily return. This mechanism uses a stack—a last-in, first-out list—to keep track of the directories you've saved. While not a common requirement, it is possible to inspect the state of this directory stack using the special, built-in %DIRCMD% variable.

This guide will explain what the PUSHD directory stack is, how the %DIRCMD% variable reflects its state, and demonstrate a practical (though rare) use case for this advanced scripting variable.

A Refresher: What is the PUSHD / POPD Directory Stack?​

Before understanding %DIRCMD%, you must understand the directory stack.

  • PUSHD "path": This command does two things:
    1. It stores (pushes) your current directory onto the top of a memory stack.
    2. It then changes to the new directory specified in "path".
  • POPD: This command reads the directory path from the top of the stack and changes back to it. It then removes (pops) that entry from the stack.

This is extremely useful for a script that needs to temporarily visit another location to perform a task and then reliably return to its starting point.

The Core Variable: %DIRCMD%​

The %DIRCMD% variable is a read-only, dynamic variable that holds the current value of the directory stack. It is a special, undocumented variable that is managed directly by cmd.exe.

The value it holds is a string of the full paths of all the directories currently stored in the stack, separated by a special character (a vertical pipe |).

Basic Example: Watching %DIRCMD% Change​

This script uses PUSHD to move through several directories and shows how the %DIRCMD% variable changes with each step.

@ECHO OFF
SETLOCAL ENABLEDELAYEDEXPANSION

ECHO --- Exploring the Directory Stack ---
ECHO.
ECHO Initially, the stack is empty.
ECHO DIRCMD is: "%DIRCMD%"
ECHO.
PAUSE

PUSHD "C:\Windows"
ECHO Pushed C:\Windows.
ECHO DIRCMD is now: !DIRCMD!
ECHO.
PAUSE

PUSHD "C:\Program Files"
ECHO Pushed C:\Program Files.
ECHO DIRCMD is now: !DIRCMD!
ECHO.
PAUSE

POPD
ECHO Popped the stack once.
ECHO DIRCMD is now: !DIRCMD!
ECHO Current directory is: %CD%
ECHO.
PAUSE

POPD
ECHO Popped the stack again.
ECHO DIRCMD is now: "%DIRCMD%"
ECHO Current directory is: %CD%

ENDLOCAL
note

DelayedExpansion (!DIRCMD!) is used to see the updated value inside the same session.

How to "Read" the Value of %DIRCMD%​

The output of the previous script shows how the stack is stored as a string:

  • After the first PUSHD, %DIRCMD% contains the original starting path.
  • After the second PUSHD, %DIRCMD% contains C:\OriginalPath|C:\Windows. The newest entry is on the right.

The number of directories on the stack is essentially the number of pipe characters (|) in the string, plus one. This means we can "count" the stack size.

Common Pitfalls and How to Solve Them​

  • Undocumented and Obscure: %DIRCMD% is not an officially documented variable. While it has been present in cmd.exe for many versions, its behavior is not guaranteed. For this reason, it's rarely used in production scripts. Most scripts simply trust that POPD will work and do not bother to check the stack size.

  • Parsing is Difficult: Parsing the |-separated string is possible in batch but very complex. You would need a FOR /F loop with a custom delimiter to count the items.

  • No Direct "Stack Size" Variable: There is no simple %DIRCMD_SIZE% variable. Getting the stack depth requires the complex parsing mentioned above.

Practical Example: A Safe POPD Script​

This is one of the few practical use cases for %DIRCMD%. A common error is to call POPD when the directory stack is already empty. This will produce an error message. This script checks %DIRCMD% to ensure the stack is not empty before it calls POPD.

@ECHO OFF
SETLOCAL

ECHO --- Safe POPD Demonstration ---
ECHO.
PUSHD "C:\Windows"
ECHO Pushed a directory. Current location: %CD%

ECHO.
CALL :SafePopd
ECHO Returned to: %CD%

ECHO.
ECHO --- Now, try to pop from an empty stack ---
CALL :SafePopd

ENDLOCAL
GOTO :EOF


:SafePopd
    ECHO Checking if the directory stack is empty...
    IF NOT DEFINED DIRCMD (
        ECHO   -> Stack is empty. Cannot POPD.
    ) ELSE (
        ECHO   -> Stack has content. Popping now...
        POPD
    )
GOTO :EOF

How it works: When the stack is empty, the %DIRCMD% variable becomes undefined. The IF NOT DEFINED DIRCMD check is a simple and reliable way to see if there is anything on the stack to be popped.

Conclusion​

The %DIRCMD% variable is an obscure but interesting feature of the command processor that gives you a direct view into the state of the PUSHD/POPD directory stack.

  • It stores the entire directory stack as a single, |-separated string.
  • It is undefined when the stack is empty.
  • Its most practical use is to check if the stack is empty before calling POPD to avoid an error, using the IF NOT DEFINED DIRCMD command.

While it is not a variable you will need for everyday scripting, understanding %DIRCMD% provides a deeper insight into how the cmd.exe shell manages its state.

Table of Contents