Name: rename

Type: command

Syntax: rename [{file | folder | directory}] <filePath> to <newPath>

Summary:
Gives a <file> or <folder> a new name or moves it to a new location or
both. 

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
rename file "Foo.txt" to "Bar.txt"

Example:
rename folder "/bin/utilities/help" to "/public/utilities/new-help"

Parameters:
filePath:
The filePath specifies the current name and location of the file or
folder you want to rename or move. If you specify a name but not a
location, LiveCode assumes the file or folder is in the defaultFolder.

newPath:
The newPath specifies the new name and location of the file or folder.

Description:
Use the <rename> <command> to change the name or location of a
<file(keyword)> or <folder>.

The <rename> <command> can be used to change a <file(glossary)|file's>
or <folder|folder's> location only if the old and new locations are both
on the same volume.

>*Warning:*  This <command> can be used to rename or move <files> and
> <folders> your stack did not create. Of course, a <stack> should not
> rename or move <files> and <folders> it didn't create without
> obtaining explicit confirmation from the user.

>*Warning:* If a file with the same file path as the newPath already exists, 
> that file will be overwritten without confirmation.

>*Cross-platform note:* On Windows, if a file with the same file path as newPath already
> exists then the rename operation will fail. On other platforms, the existing file may be
> overwritten. If the operation does fail, then the result will be "can't rename file".
> Note that a rename operation may fail on any operating system, so it's important to
> check the result afterwards.

Changes:
The ability to move a file or folder on Mac OS and Windows systems with
the rename command was introduced in version 1.1.1. In previous
versions, the rename command could be used only to change the name, not
the location.

References: revCopyFile (command), create alias (command),
tempName (function), files (function), folders (function),
command (glossary), file (glossary), folder (glossary), file (keyword),
stack (object), fileType (property)

Tags: file system

