RunMat
GitHub

View all functions

CategoryIo: Repl Fs

cd — Change the current working folder or query the folder that RunMat is executing in.

cd displays the current working folder or switches RunMat to a different folder. It mirrors MATLAB so scripts and interactive sessions can rely on the same workspace layout when loading files, saving artifacts, or invoking other builtins that reference relative paths.

How does the cd function behave in MATLAB / RunMat?

  • cd with no input returns the absolute path of the current folder as a character row vector (1×N).
  • cd(newFolder) changes the working folder and returns the previous folder, enabling the classic MATLAB pattern old = cd(new); ...; cd(old);.
  • Accepts character vectors and string scalars. String arrays must contain exactly one element. Other types raise cd: folder name must be a character vector or string scalar.
  • Supports relative paths (for example cd('..')), absolute paths, and the shell-style ~ expansion to jump to the user home folder.
  • Emits descriptive errors when the folder does not exist or cannot be accessed.
  • Does not modify GPU residency; path values always live on the host.

GPU behavior

cd performs host-side path manipulation and process-level directory changes. When callers supply the folder argument from GPU memory, RunMat gathers the value before resolving the new path. Providers are not expected to implement hooks for this builtin, and no GPU kernels run as part of cd.

GPU residency

cd operates entirely on the CPU, so there is no performance benefit to moving folder arguments onto the GPU. If a path value is already wrapped in gpuArray, RunMat transparently gathers it before resolving the change directory request. Scripts can keep using plain character vectors or string scalars without worrying about residency.

Examples of using cd in MATLAB / RunMat

Display The Current Working Folder In RunMat

current = cd

Expected output:

% current is the absolute path to the folder where RunMat is executing

Change Directory To A Project Subfolder

projectRoot = pwd;
mkdir("data/logs");
old = cd("data/logs");
% ... work inside the logs folder ...
cd(old)

Expected output:

% old contains the previous folder so you can restore it later, and the final cd(old)
% call brings you back to projectRoot

Navigate Up One Level From The Current Folder

old = cd("..")

Expected output:

% RunMat moves to the parent folder and old captures the prior location

Switch To Your Home Folder With cd ~

old = cd("~")

Expected output:

% Changes to the user home directory; old stores the previous folder

Capture The Previous Folder And Restore Later

old = cd("results");
% ... run code that writes outputs into results ...
cd(old)

Expected output:

% The working folder is restored to its original location at the end

Handle Missing Folders With A try/catch Block

try
    cd("missing-folder");
catch err
    disp(err.message);
end

Expected output:

% Displays a descriptive error such as:
% "cd: unable to change directory to 'missing-folder' (No such file or directory)"

FAQ

Does cd return the new folder or the old folder?

When you pass an input, cd returns the previous folder so that you can restore it later. Calling cd with no input returns the current folder.

Can I pass GPU-resident strings to cd?

Yes. RunMat gathers any GPU scalar arguments automatically before resolving the path.

Is tilde (~) expansion supported?

Yes. cd('~') and cd('~/subdir') jump to the user home folder. Other leading ~ patterns are treated literally so existing MATLAB scripts continue to work on platforms that support them.

How are relative paths resolved?

Relative folders are interpreted with respect to whatever cd reports as the current folder, exactly like MATLAB.

What happens if the target folder does not exist?

cd throws an error that includes both the requested folder and the underlying operating system message.

Can I change to folders whose names include spaces?

Yes. Provide them as strings or character vectors—RunMat preserves whitespace exactly.

See also

pwd, ls, dir, fileread

Source & Feedback