movefile — Move or rename files, directories, or wildcard matches.
movefile changes filesystem paths and returns status with optional diagnostics.
Syntax
[status, msg, msgID] = movefile(source, destination)
[status, msg, msgID] = movefile(source, destination, flag)Inputs
source- Type
StringScalar- Required
- Yes
- Description
- Source file, directory, or wildcard pattern.
destination- Type
StringScalar- Required
- Yes
- Description
- Destination file or directory path.
flag- Type
StringScalar- Required
- Yes
- Default
'f'- Description
- Case-insensitive 'f' flag that permits replacement of an existing target.
Returns
status- Type
NumericScalar- Description
- Double scalar 1 after success or 0 after an operational failure.
msg- Type
StringScalar- Description
- Character-row diagnostic, empty after success.
msgID- Type
StringScalar- Description
- Character-row diagnostic identifier, empty after success.
Returned values from movefile depend on how many outputs the caller requests.
Errors
RunMat:movefile:NotEnoughInputs- When
- Fewer than two inputs are provided.
- Message
movefile: not enough input arguments
RunMat:movefile:TooManyInputs- When
- More than three inputs are provided.
- Message
movefile: too many input arguments
RunMat:movefile:SourceArgType- When
- Source is not a character row or string scalar.
- Message
movefile: source must be a character vector or string scalar
Move and rename files
movefile(source, destination) renames one file or directory or moves it to another directory. A source containing wildcards moves every match into an existing destination directory.
Pass 'f' as the third argument to replace a compatible existing destination. Without that flag, an existing target is preserved and the operation reports failure. Replacement uses the filesystem provider's rename operation; it does not delete the destination first. Incompatible types, nonempty destination directories, unsupported providers, and cross-filesystem moves can fail while preserving the source and destination.
Results and execution
status is a double scalar: 1 after success and 0 after an operational failure. msg and msgID are empty character rows after success and describe a failure otherwise. Without outputs, an operational failure raises an error. Invalid argument types and malformed flags raise an error before filesystem access.
Paths accept character rows and scalar strings. Relative paths use the current folder and a leading ~ expands through the active environment. The operation runs through the host or browser filesystem service. Numeric and provider-resident path values reject without a device transfer; no accelerator kernel is used.
The active filesystem provider defines cross-volume behavior and metadata preservation. If its rename operation cannot move between two storage volumes, movefile returns status 0 with the provider error and leaves recovery to the caller.
Cancellation is checked before filesystem mutation and between wildcard entries. Wildcard moves are sequential and nontransactional: files completed before an error or cancellation remain moved.
Examples
Rename a file
root = tempname();
mkdir(root);
source = fullfile(root, 'results.txt');
target = fullfile(root, 'archive.txt');
fid = fopen(source, 'w'); fclose(fid);
status = movefile(source, target);
sourceAfter = exist(source, 'file');
targetAfter = exist(target, 'file');
rmdir(root, 's');Expected output:
status is double 1, the source is absent, and the target existsMove a file into a directory
root = tempname();
mkdir(root);
mkdir(root, 'reports');
source = fullfile(root, 'summary.txt');
fid = fopen(source, 'w'); fclose(fid);
status = movefile(source, fullfile(root, 'reports'));
moved = exist(fullfile(root, 'reports', 'summary.txt'), 'file');
rmdir(root, 's');Expected output:
the source name is retained inside the destination directoryReplace an existing file
root = tempname();
mkdir(root);
source = fullfile(root, 'draft.txt');
target = fullfile(root, 'final.txt');
fid = fopen(source, 'w'); fclose(fid);
fid = fopen(target, 'w'); fclose(fid);
[status, msg, msgID] = movefile(source, target, 'f');
rmdir(root, 's');Expected output:
status is 1 and both diagnostic character rows are emptyMove every wildcard match
root = tempname();
mkdir(root);
mkdir(root, 'data');
fid = fopen(fullfile(root, 'a.log'), 'w'); fclose(fid);
fid = fopen(fullfile(root, 'b.log'), 'w'); fclose(fid);
status = movefile(fullfile(root, '*.log'), fullfile(root, 'data'));
first = exist(fullfile(root, 'data', 'a.log'), 'file');
second = exist(fullfile(root, 'data', 'b.log'), 'file');
rmdir(root, 's');Expected output:
both matching files are movedInspect a missing-source result
root = tempname();
mkdir(root);
[status, msg, msgID] = movefile(fullfile(root, 'missing.txt'), fullfile(root, 'dest.txt'));
rmdir(root);Expected output:
status is 0 and the diagnostic rows identify the failureLeave a file in place when both paths match
root = tempname();
mkdir(root);
source = fullfile(root, 'stable.txt');
fid = fopen(source, 'w'); fclose(fid);
status = movefile(source, source);
stillPresent = exist(source, 'file');
rmdir(root, 's');Expected output:
status is 1 and the file remains at the same pathUsing movefile with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how movefile changes the result.
Run a small movefile example, explain the result, then change one input and compare the output.
FAQ
How do I replace an existing target?⌄
Pass 'f' as the third argument. Without it, movefile leaves the existing target unchanged and returns status 0.
Can movefile move several files?⌄
Yes. Use a wildcard source and an existing destination directory. Every match is planned before the first move begins. The moves execute in sequence, not as one transaction; an error can leave earlier matches already moved.
Can movefile cross storage volumes?⌄
Only when the active filesystem provider supports that rename. An unsupported cross-volume move returns status 0 and provider diagnostics.
Can movefile run on a GPU?⌄
No. Filesystem access is a host-service operation, and path inputs must be host text.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · filesep · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · memmapfile.subsasgn · memmapfile.subsref · mkdir · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · getvaropts · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · setvaropts · setvartype · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Data
commit · data.copy · data.create · data.delete · data.exists · data.export · data.import · data.inspect · data.list · data.move · data.open · DataArray.chunk_shape · DataArray.codec · DataArray.dtype · DataArray.fill · DataArray.name · DataArray.rank · DataArray.read · DataArray.resize · DataArray.shape · DataArray.write · Dataset.array · Dataset.arrays · Dataset.attrs · Dataset.begin · Dataset.get_attr · Dataset.has_array · Dataset.id · Dataset.path · Dataset.refresh · Dataset.set_attr · Dataset.set_attrs · Dataset.snapshot · Dataset.version · DataTransaction.abort · DataTransaction.commit · DataTransaction.create_array · DataTransaction.delete_array · DataTransaction.fill · DataTransaction.id · DataTransaction.resize · DataTransaction.set_attr · DataTransaction.set_attrs · DataTransaction.status · DataTransaction.write
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Source you can read
Every RunMat function's source is public. Read exactly how movefile is executed, line by line, in Rust.
- View the source for movefile in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.