movefile — Move or rename files and folders with MATLAB-compatible status, message, and message ID outputs.

movefile renames files and folders or moves them to a new location. It mirrors MATLAB by returning status information instead of throwing errors for filesystem failures and by accepting the optional 'f' flag to overwrite destinations.

How movefile works in RunMat

• status = movefile(source, destination) moves or renames source. status is a double scalar that is 1 on success and 0 on failure.
• [status, message, messageID] = movefile(...) also returns MATLAB-style diagnostic text. Successful operations populate both strings with empty character arrays (1×0).
• movefile(source, destination, 'f') forces the move, overwriting an existing destination file or folder. Without the flag, movefile refuses to overwrite existing targets.
• Wildcards in source (such as *.m) expand to matching filesystem entries. When the pattern resolves to multiple items, destination must be an existing folder and movefile moves each match into that folder.
• Inputs accept character vectors or string scalars. Other types raise MATLAB-style errors before any filesystem work occurs.
• Paths are resolved relative to the current working directory (pwd) and expand a leading ~ into the user's home directory.
• Filesystem failures—including missing files, permission errors, or read-only destinations—return status = 0 plus descriptive diagnostics; only invalid inputs raise immediate errors.

How movefile runs on the GPU

movefile performs host-side filesystem operations. When acceleration providers are active, RunMat first gathers any GPU-resident arguments (for example, gpuArray("logs")), executes the move on the CPU, and returns host-resident outputs. Providers do not expose special hooks for this builtin, so GPU execution is not applicable.

GPU memory and residency

No. movefile always runs on the host CPU, so storing paths on the GPU offers no benefit. If a string argument is already GPU-resident, RunMat gathers it automatically before touching the filesystem so existing scripts continue to work unchanged.

Examples

Rename a file in the same folder

fid = fopen("results.txt", "w"); fclose(fid);
status = movefile("results.txt", "archive.txt")

Expected output:

status =
     1

Move a file into an existing folder

mkdir("reports");
fid = fopen("summary.txt", "w"); fclose(fid);
status = movefile("summary.txt", "reports")

Expected output:

status =
     1

Force overwrite an existing destination

fid = fopen("draft.txt", "w"); fclose(fid);
fid = fopen("final.txt", "w"); fclose(fid);
[status, message, messageID] = movefile("draft.txt", "final.txt", "f")

Expected output:

status =
     1
message =

messageID =

Move multiple files with a wildcard

mkdir("data");
fid = fopen("a.log", "w"); fclose(fid);
fid = fopen("b.log", "w"); fclose(fid);
status = movefile("*.log", "data")

Expected output:

status =
     1

Handle missing sources gracefully

[status, message, messageID] = movefile("missing.txt", "dest.txt")

Expected output:

status =
     0
message =
Source "missing.txt" does not exist.
messageID =
RunMat:MOVEFILE:FileDoesNotExist

Use gpuArray inputs for paths

fid = fopen("draft.txt", "w"); fclose(fid);
status = movefile(gpuArray("draft.txt"), gpuArray("final.txt"))

Expected output:

status =
     1

FAQ

What status codes does movefile return?

1 indicates every requested move succeeded; 0 indicates that nothing was moved. Status values are doubles so existing MATLAB scripts continue to work.

Does movefile throw exceptions?

Only invalid inputs raise errors. Filesystem failures surface through the status, message, and message ID outputs.

How do I overwrite an existing file?

Pass the 'f' flag as the third argument. Without it, movefile refuses to overwrite existing files or folders.

Can I move multiple files at once?

Yes. Include wildcards such as *.txt in source. The destination must be an existing folder in that case.

Does movefile work with folders?

Yes. It can move or rename entire folders. When moving into another folder and the target name already exists, pass 'f' to overwrite it.

How are paths resolved?

Paths are resolved relative to pwd, and a leading ~ expands to the user's home directory.

Will GPU acceleration speed up movefile?

No. The builtin executes on the host CPU. GPU-resident strings are gathered automatically before performing the move.

What happens if no files match a wildcard?

The function returns status = 0, sets message to "Source \"pattern\" does not exist.", and leaves the filesystem unchanged.

Does the function preserve timestamps or permissions?

Yes. movefile forwards the operation to the operating system, which preserves attributes when possible.

Can I move directories across volumes?

When the underlying operating system reports an error (for example, moving across volumes without rename support), movefile returns status = 0 along with the system error text so you can handle it programmatically.

Related functions to explore

These functions work well alongside movefile. Each page has runnable examples you can try in the browser.

copyfile, mkdir, rmdir, dir, pwd, addpath, cd, delete, exist, fullfile, genpath, getenv, ls, path, rmpath, savepath, setenv, tempdir, tempname

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how movefile works, line by line, in Rust.

• View movefile.rs on GitHub
• Learn how the runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing