These docs are under active development and cover the v0.20 Kobicha security model.
Peios Learn
On this page
reference 2 min read

mv

mv moves files and directories from one place to another. Moving a file within the same directory, under a new name, is how you rename it.

mv [options] source dest
mv [options] source... directory
mv [options] -t directory source...

$ mv draft.txt report.txt                 # rename
$ mv report.txt notes.txt /home/jack/done/ # move into a directory

A move is either a rename or a copy-and-delete

mv does its job in one of two ways, and which one decides what happens to the file's security.

Within one file system, a move is a rename. Nothing is copied: the file stays exactly where it physically is, and only its name and directory entry change. The file keeps its inode, and so it keeps its security descriptor unchanged — every owner, access rule, audit rule, and timestamp is exactly as before. A rename does not re-evaluate inheritance; a file does not pick up new rules just because it landed in a new directory.

Across file systems, a move is a copy followed by a delete. When the destination is on a different file system, mv cannot just rename — it copies the data to a new file on the destination, then removes the original. That new file is a genuinely new object, so, exactly as with cp, it gets a fresh security descriptor inherited from the destination directory unless you ask otherwise.

So: rename a file and its security is untouched; move it to another file system and the copy starts fresh.

Preserving security on a cross-file-system move

For the copy-and-delete case, mv carries the same --preserve family that cp does — an identical set of options, behaving the same way. They let a cross-file-system move carry the source's owner, access rules, timestamps, and other attributes onto the new file instead of taking the destination directory's inherited default.

The full --preserve reference — the attribute list, --sd, --sd-explicit, --preserve-all, --no-preserve, and what happens when a preserve cannot be honoured — is on the cp page. Everything there applies to mv unchanged.

On a same-file-system move the --preserve options have nothing to do: a rename already keeps every attribute, because it is the same file.

Overwriting an existing destination

By default mv overwrites an existing destination. These options change that. When more than one of -i, -f, -n is given, the last one wins.

Option Effect
-i, --interactive Ask before overwriting an existing file.
-f, --force Do not prompt before overwriting.
-n, --no-clobber Never overwrite an existing file.
-u, --update[=WHICH] Overwrite only when the source is newer. WHICH can be all, none, or older.
-b, --backup[=CONTROL] Make a backup of the destination before overwriting it.

Other options

Option Effect
-t, --target-directory=DIR Move every source into DIR.
-T, --no-target-directory Treat dest as a plain file even if it is a directory.
--strip-trailing-slashes Strip any trailing slashes from each source argument.
-v, --verbose Print each file as it is moved.
--debug Explain in detail how each file was moved. Implies -v.
--progress Show a progress bar.

Exit status

Code Meaning
0 Every file was moved successfully.
1 A file could not be moved.

See also