Table of Contents

rename

Free

Description

Renames a specified file.

Syntax

rename -filePath -value -search

Use -id as an alternative to -filePath for the same operand. A required target still needs one selector, even though each alternative is optional individually. See File IDs and paths for selection rules and command-specific exceptions.

Parameters

Parameter Alias Required Description
-filePath No The filerename.
-value -val No The new name for the file. You must include the extension.
-search No The search operation to use.
-directory -dir No The directory to rename.
-id No Positive PDM file ID instead of -filePath, identifying the same file that -filePath describes (including a macro, input CSV or existing output file). Requires a connected vault. Shared files with multiple locations require an exact -filePath. Resolving the ID itself does not download, check out or check in the file; the requested command still performs its normal operation.

Examples

rename -filePath "oldname.sldprt" -val "newname.sldprt"

Remarks

  • The search parameter searches the current directory and does not drill down. The search query is a PDM one, so you can use % for wildcard.

Value Evaluation

The value parameter gets evaluated by PDMShell. PDMShell allows you to use placeholders in the new name, which will be replaced with actual values from the file. This can be useful to dynamically generate new names based on file properties or other variables. The following placeholders are supported:

  • $filename - The file name without extension.
  • $id - The file ID.
  • $revision - The current revision of the file.
  • $date - The current date.
  • $time - The current time.
  • $version - The current version of the file.
  • $extension - The file extension.

Additionally, you can use PDM variable expressions such as $(VariableName.ConfigurationName) to include values from other variables. For file variables, include the configuration suffix. Use .@ for the file @ tab, for example $(Revision.@). Bracketed text is treated as literal text and is not evaluated.

String functions are also supported after placeholders are evaluated. For example, ${replace($fileNameWithoutExtension, " ", "_")} replaces spaces in the file name before the rename value is written. Use ${before($fileNameWithoutExtension, "-")} to keep only the part of the name before a separator.

Note

Please read more information about placeholder evaluation here.

Examples

If you use the value "$filename_$date_$version$extension", it will be replaced with the file name, current date, and version, resulting in something like "oldname_10-12-2023_3".

rename -filePath "oldname.sldprt" -value "$fileNameWithoutExtension $(Revision.@)$extension"

rename -filePath "Part 123 Draft.sldprt" -value "${left(${replace($fileNameWithoutExtension, \" \", \"_\")}, 12)}$extension"

rename -filePath "ABC-123.sldprt" -value "${before($fileNameWithoutExtension, \"-\")}$extension"

Search results report

Add -csv "C:\Reports\results.csv" when using -search to save operation results. The first columns are file ID, parent folder ID, file name and output, followed by status and error details. The report folder must exist. New vault reports are added to PDM; existing vault reports must be checked out by you on this computer and remain checked out. External reports are replaced. See CSV operation reports for command-specific outcomes.