Scripting Reference

Previous Up Next

A script is a simple text file containing a list of commands which can control the program and automatically perform file operations or produce reports.  See also Scripts and Sample Scripts.

Notation

Meaning

|

delimits the possible choices

()

surrounds a required expression

[]

surrounds an optional expression

<>

surrounds the description of required user text

[...]

follows an expression that can be repeated

You can use lt in place of left or rt in place of right in any of the commands.

These are the script commands (in alphabetical order):

ATTRIB BEEP COLLAPSE COMPARE COPY COPYTO CRITERIA DATA-REPORT DELETE EXPAND FILE-REPORT FILTER FOLDER-REPORT HEX-REPORT LOAD LOG MOVE MOVETO MP3-REPORT OPTION PICTURE-REPORT REGISTRY-REPORT RENAME SELECT SNAPSHOT SYNC TEXT-REPORT TOUCH VERSION-REPORT


ATTRIB

Usage:

attrib (+|-)<attribute set 1> [(+|-)<attribute set 2> [...]]

 

Where <attribute set> is:

[a][s][h][r]

 

The Mac and Linux versions do not support attrib.

Sets (+) or clears (-) the DOS file attributes in the current selection.  Use a for archive, s for system, h for hidden and r for read-only.

Examples:

attrib +h

attrib +sh -a

 


BEEP

Usage:

beep

 

Beeps the PC speaker.  The beep occurs regardless of the /silent command line switch.


COLLAPSE

Usage:

collapse all

collapse <path 1> [<path 2> [...]]

 

Collapses all folders or folders with specified paths.  Paths are relative to the base folder and can not have wildcards.

Example:

collapse "My Folder 1" "My Folder 2"

 


COMPARE

Usage:

compare [CRC|binary|rules-based]

 

Compares the contents of the current selection using the compare type.  By default, the most recent compare type is used.

This command only compares files once.  To change how files are compared after modification, use CRITERIA.


COPY

Usage:

copy (left->right|right->left)

 

Copies the selected files/folders in the direction indicated.


COPYTO

Usage:

copyto [left|right|all] [path:(relative|base|none)] <path>

 

Copies the selected files/folders on the specified side to the specified path using the path option.

base keeps the entire folder structure relative to the base folders of all selected items.

relative keeps the minimum relative folder structure of all selected items.

The defaults are all and path:none.

 


CRITERIA

Usage:

criteria [attrib:<attribute set>] [version] [timestamp[:[<number of seconds>sec][;IgnoreDST]]] [size|CRC|binary|rules-based] [timezone:(ignore|(left|right)(+|-)<0..12>)] [follow-symlinks] [ignore-unimportant]

 

Where <attribute set> is:

[a][s][h][r]

 

The Mac and Linux versions do not support attrib.

Sets all comparison criteria settings.

attrib enables comparisons of the specified DOS file attributes.  Use a for archive, s for system, h for hidden and r for read-only.

version enables comparisons of version information common in exes and dlls.

timestamp enables timestamp comparisons.

o<number of seconds>sec considers differences within a tolerance of seconds as matches.

oIgnoreDST considers differences of exactly 1 hour as matches.

size, CRC, binary and rules-based are the possible ways to compare contents.

timezone ignores timezone differences or applies timezone offset to the specified side.

follow-symlinks treats symbolic links and NTFS junctions as the target file or folder, rather than the link itself.

ignore-unimportant treats unimportant differences as matches.

Example:

criteria attrib:sh timestamp:2sec;IgnoreDST rules-based timezone:left+6

 


DATA-REPORT

Usage:

data-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>] [<comparison>]

 

Generates a Table Compare report of the currently selected files.

layout controls the report's appearance and can be side-by-side, summary or interleaved.

options is optional and is used differently for each layout.

oignore-unimportant treats differences in unimportant text as matches and is available in all layouts.

odisplay-all, display-mismatches or display-matches can be used to control which lines of the comparison are included in all layouts except summary.  By default, display-all is used.

oline-numbers includes row numbers in the side-by-side layout.

title, output-to, output-options and <comparison> arguments are documented under Common Report Arguments.


DELETE

Usage:

delete [recyclebin=(yes|no)] (left|right|all)

 

Deletes the currently selected files/folders on the specified side(s).  The recyclebin argument only has effect where supported by the operating system.  Network drives, remote services and archive files do not support it.


EXPAND

Usage:

expand all

expand <path 1> [<path 2> [...]]

 

Expands specified subfolders or all subfolders.  Paths are relative to the base folder and can not have wildcards.  Subfolders must be expanded in order for their contents to be used by other commands, like SELECT. expand all will not expand subfolders that have been excluded from the comparison by File Filter settings.


FILE-REPORT

Usage:

file-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>] [<comparison>]

 

Generates a report of the currently selected files based on the type of files processed.  For example, it will produce a DATA-REPORT for file types associated with a Table Compare file format.

layout controls the report's appearance and can be side-by-side or summary.

options is optional and is used differently for each layout.

oignore-unimportant treats differences in unimportant text as matches and is available in all layouts.

odisplay-all, display-mismatches or display-matches can be used to control which lines of the comparison are included in all layouts except summary.  By default, display-all is used.

oline-numbers includes line numbers in the side-by-side layout.

title, output-to, output-options and <comparison> arguments are documented under Common Report Arguments.

Example:

file-report layout:side-by-side options:display-mismatches &

   output-to:printer output-options:print-color,wrap-word

 


FILTER

Usage:

filter <file masks>

filter cutoff:([<|>](<timestamp>|<number of days>[days])|none)

filter attrib:((+|-)<attribute set>|none)

filter size:([<|>]<number>[KB|MB|GB|TB]|none)

filter exclude-protected

filter include-protected

 

Where <attribute set> is:

[a][s][h][r]

 

The Mac and Linux versions do not support attrib, exclude-protected or include-protected.

Controls which folders and types of files are compared by using name filtering (file masks), date filtering (cutoff) or other filtering (attrib, size, exclude-protected or include-protected).

Name filters include and exclude files and folders based on their names and paths.  Multiple masks can be separated by semicolons.  To indicate that a mask is an exclude mask use a leading minus (-).  To indicate that a mask affects folders use a trailing backslash (\).

cutoff excludes all files older (<) or newer (>) than a timestamp or a number of days from the current system date (<number of days>days).  By default, cutoff:< is used. none can be used to remove date filtering.  The date parsing is fairly lenient but if you want to be sure it parses correctly, use the format specified by the operating system's regional settings.  (See Control Panel > Regional and Language Settings.)  The time is optional and should follow the date (cutoff:"12/31/2012 12:00pm").  Remember to use quotation marks (" ") whenever a term contains a space.

attrib limits the comparison to files which have an included DOS file attribute (+) and don't have an excluded attribute (-).  Use a for archive, s for system, h for hidden and r for read-only. none can be used to remove attribute filtering.

size excludes all files smaller (<) or larger (>) than the given size.  By default the size is given in bytes but you can add KB, MB, GB or TB to the end to indicate that the value is in kilobytes, megabytes, gigabytes or terabytes, respectively. none can be used to remove size filtering.

exclude-protected excludes files and folders that have both system and hidden attributes set.

include-protected includes files and folders that have both system and hidden attributes set.

Examples:

filter "*.pas;*.dpr;*.dfm"

filter cutoff:<7days

filter cutoff:>"Dec 31, 2012"

filter cutoff:"12/31/2012 12:00pm"

filter attrib:-sh

filter "*.txt;-My Folder\" attrib:+r

 


FOLDER-REPORT

Usage:

folder-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>]

 

Generates a folder comparison report of the currently loaded base folders.  Folders are shown in their current state.  To include subfolders add an expand all command before this.

layout controls the report's appearance and can be side-by-side, summary or xml.

options is optional.

oDisplay filter flags control which files are included in the report.  The possible values are display-all, display-mismatches, display-no-orphans, display-mismatches-no-orphans, display-orphans, display-left-newer, display-right-newer, display-left-newer-orphans, display-right-newer-orphans and display-matches.  By default, display-all is used.

oOptional columns can be included, separated by commas, in the report by using the flags column-version, column-size, column-crc, column-timestamp, column-attributes, column-group, column-owner and column-vcs.  By default, column-size and column-timestamp are included. column-none can be used by itself to clear the default columns.

oUse the flag include-file-links to generate file reports and include links to them in the folder report.  Only a folder report that is both side-by-side and HTML can use this flag.

title, output-to and output-options arguments are documented under Common Report Arguments.

Examples:

folder-report layout:side-by-side &

   options:column-size,column-version,column-timestamp &

   output-to:clipboard output-options:html-color

folder-report layout:xml output-to:"C:\My Report.xml"

 


HEX-REPORT

Usage:

hex-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>] [<comparison>]

 

Generates a Hex Compare report of the currently selected files.

layout controls the report's appearance and can be side-by-side, summary or interleaved.

options is optional and is used differently for each layout.

odisplay-all, display-mismatches or display-matches can be used to control which lines of the comparison are included in all layouts except summary.  By default, display-all is used.

oline-numbers includes byte addresses in the side-by-side layout.

title, output-to, output-options and <comparison> arguments are documented under Common Report Arguments.


LOAD

Usage:

load <session>

load [create:(all|left|right)] <left path> [<right path>]

load <default>

 

Loads the specified Folder Compare session, the specified base folders or a new Folder Compare session with default settings (load <default>).  Failure to load a base folder will cause the script to terminate.

Loading a session causes all that session's settings, except the display filter (show all, only mismatches, only matches, etc.), to be used.

Loading base folders uses the currently active settings.  By default, the program defaults are used.

The optional create parameter creates a base folder if it doesn't already exist.

Examples:

load "My Session"

load "C:\My Folder" "X:\Your Folder"

load <default>

 


LOG

Usage:

log [none|normal|verbose] [[append:]<filename>]

 

Controls how detailed the log is and where the log is stored.

none, normal and verbose determine the amount of detail used in the log.  Logging is initially disabled and begins when the mode is changed from none.

append: causes logging to add to the file instead of replace it.  By default, the log is output as Log.txt in the current folder (e.g. the Windows "Start In" folder in shortcut properties).


MOVE

Usage:

move (left->right|right->left)

 

Moves the selected files/folders in the direction specified.


MOVETO

Usage:

moveto [left|right|all] [path:(relative|base|none)] <path>

 

Moves the selected files/folders on the specified side to the specified path using the path option.

base keeps the entire folder structure relative to the base folders of all selected items.

relative keeps the minimum relative folder structure of all selected items.

The defaults are all and path:none.

 


MP3-REPORT

Usage:

mp3-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>] [<comparison>]

 

Generates an MP3 Compare report of the currently selected files.

layout controls the report's appearance and can be side-by-side or summary.

options is optional and is used differently for each layout.

oignore-unimportant treats differences in unimportant text as matches and is available in all layouts.

odisplay-all, display-mismatches or display-matches can be used to control which lines of the comparison are included in all layouts except summary.  By default, display-all is used.

title, output-to, output-options and <comparison> arguments are documented under Common Report Arguments.


OPTION

Usage:

option stop-on-error

option confirm:(prompt|yes-to-all|no-to-all)

 

Adjusts script processing options.

stop-on-error makes the script watch for various error conditions, including file operation errors, and, when one occurs, prompts the user before continuing.

confirm can use prompt, yes-to-all or no-to-all to handle confirmation dialogs that occur due to file operations.  By default, prompt is used.


PICTURE-REPORT

Usage:

picture-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>] [<comparison>]

 

Generates a Picture Compare report of the currently selected files.

layout controls the report's appearance and can be side-by-side or summary.

options is optional and is used differently for each layout.

oignore-unimportant treats differences in unimportant text as matches in the summary layout.

title, output-to, output-options and <comparison> arguments are documented under Common Report Arguments.


REGISTRY-REPORT

Usage:

registry-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>] [<comparison>]

 

Generates a Registry Compare report of the currently selected files.

layout controls the report's appearance and can be side-by-side or summary.

options is optional and is used differently for each layout.

odisplay-all, display-mismatches or display-matches can be used to control which lines of the comparison are included in all layouts except summary.  By default, display-all is used.

title, output-to, output-options and <comparison> arguments are documented under Common Report Arguments.


RENAME

Usage:

rename [regexpr <old mask>] <new mask>

 

Performs a multi-file rename on the current selection using the specified new mask. regexpr uses an old mask to perform a regular expression rename.  By default, a DOS-style rename is performed.

Examples:

rename *.bak

rename regexpr (...)(...)\.txt $2$1.txt

 


SELECT

Usage:

select <selection mask 1> [<selection mask 2> [...]]

 

Where <selection mask> is one of the following:

all

[(left|right|all).][(exact|diff|newer|older|orphan|all).][(files|folders|all)]

empty.folders

 

Select controls which files and folders can be operated on.  Only files and folders that match at least one of the selection masks are part of the selection.

left, right or all limits the selection to the specified side.  By default, all is used.

exact, diff, newer, older, orphan or all limits the selection based on results of comparison. diff refers to differences in criteria other than timestamps.  To compare timestamps use newer or older instead.  Folders must contain only the specified result type to be affected.  By default, all is used.

files, folders or all limits the selection to files, folders or both.  By default, all is used.

empty.folders is a special selection mask that will select empty folders.

Examples:

select all

select left

select exact

select files

select right.diff

select left.folders

select newer.files right.older.files

 


SNAPSHOT

Usage:

snapshot [save-crc] [save-version] [expand-archives] [follow-symlinks] [include-empty] [no-filters] left|right|path:<path> [output:<target>]

 

Saves a read-only snapshot of the specified folder.

save-crc calculates CRC's for all files and stores them as part of the snapshot.

save-version stores version information for executable files.

expand-archives stores the contents of archive files in an expanded format.

follow-symlinks stores files and folders pointed to by symbolic links.

include-empty stores folders that are empty or contain only excluded files.

no-filters stores all files regardless of the active filename filters.

left, right and path indicate which folder is stored. left or right will save a snapshot of one of the loaded base folders and path will save a snapshot of a specified path.

output is optional and determines where the snapshot will be saved.  By default, it will be saved in the current folder.

oIf target is a fully qualified filename, that will be the name of the snapshot.  If target doesn't have an extension, .bcss will be used.

oIf the target isn't included or refers to a folder a filename will be generated based on the source folder's name and the current system date, eg folder_2012-12-31.bcss.  If necessary an additional number will be added to the generated name to keep it from overwriting existing snapshots.

Examples:

snapshot save-crc save-version no-filters path:C:\ output:D:\

snapshot left output:"My Snapshot.bcss"

 


SYNC

Usage:

sync [visible] [create-empty] (update|mirror):(left->right|right->left|all)

 

Synchronizes folders by copying and deleting files.  This command does not use the current selection.

visible enables "Only affect visible files" behavior.  Only files in expanded folders will be affected.

create-empty enables the "Create empty folders" behavior.

update copies newer and orphan files in the indicated direction, leaving orphans and newer files on the opposite side unchanged.  Using all as the direction indicates a bidirectional sync and copies newer and orphan files in both directions.

mirror makes the target folder identical to the source one.  Newer, older, different and orphaned files are all copied to the destination.  Orphans in the destination are deleted.  The all direction doesn't apply in this context and is not valid.

Example:

sync create-empty mirror:left->right

 


TEXT-REPORT

Usage:

text-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>] [<comparison>]

 

Generates a Text Compare report of the currently selected files.

layout controls the report's appearance and can be side-by-side, summary, interleaved, patch, statistics or xml.  Deprecated layouts over-under and composite have been replaced by interleaved.

options is optional and is used differently for each layout.

oignore-unimportant treats differences in unimportant text as matches and is available in all layouts.

odisplay-all, display-mismatches, display-context or display-matches can be used to control which lines of the comparison are included in all layouts except summary, patch and statistics.  By default, display-all is used.

oline-numbers includes line numbers in the side-by-side layout.

ostrikeout-left-diffs crosses out left difference lines in the interleaved layout.

ostrikeout-right-diffs crosses out right difference lines in the interleaved layout.

opatch-normal, patch-context or patch-unified formats are available in the patch layout.  By default, patch-normal is used.

title, output-to, output-options and <comparison> arguments are documented under Common Report Arguments.

The deprecated stats-descriptive option will generate a summary report instead and post a warning to the log.  The deprecated stats-tabular option is ignored in the statistics layout: the statistics layout is always tabular (CSV) now.

Examples:

text-report layout:interleaved options:display-context &

   output-to:printer output-options:print-color,wrap-word

text-report layout:patch options:patch-unified &

   output-to:"My Report.txt"

 


TOUCH

Usage:

touch (left->right|right->left)

touch (left|right|all):(now|<timestamp>)

 

Copies the timestamps from files on one side to the other or sets the timestamps of all files on a specified side to the current system time (now) or a specified timestamp.  You must select files before you can touch them.


VERSION-REPORT

Usage:

version-report layout:<layout> [options:<options>] [title:<report title>] output-to:(printer|clipboard|<filename>) [output-options:<options>] [<comparison>]

 

Generates a Version Compare report of the currently selected files.

layout controls the report's appearance and can be side-by-side or summary.

options is optional and is used differently for each layout.

oignore-unimportant treats differences in unimportant text as matches and is available in all layouts.

odisplay-all, display-mismatches or display-matches can be used to control which lines of the comparison are included in all layouts except summary.  By default, display-all is used.

title, output-to, output-options and <comparison> arguments are documented under Common Report Arguments.


Common report arguments

The report commands (data-report, file-report, folder-report, hex-report, mp3-report, picture-report, registry-report, text-report and version-report) must include information on where the report should be sent and may include additional information on the output format.

title controls the title that appears at the top of the report.

output-to controls the output target.  It can be printer, clipboard or a filename.

output-options is optional and is used differently for each output target.

oprint-color or print-mono color schemes are available for printer output.  By default, print-mono is used.

oprint-portrait or print-landscape orientations are available for printer output.  By default, print-portrait is used.

owrap-none, wrap-character or wrap-word control whether long lines are wrapped. printer output can use all three options. HTML output can use wrap-none and wrap-word.  By default, wrap-none is used.

ohtml-color, html-mono or html-custom are required to output as HTML instead of plain text.  These options are available for clipboard and file outputs. html-custom requires the filename or URL of an external style sheet.

<comparison> can either be a session name or a pair of filenames.  The file report will use the specified comparison instead of the files that have been selected within the script.  When using a saved session, the comparison type must match the report type (e.g. a Table Compare session must use data-report or file-report).

Examples:

data-report layout:interleaved output-to:printer &

   output-options:print-color,print-landscape

file-report layout:summary output-to:clipboard &

   output-options:wrap-word,html-color

text-report layout:patch options:patch-unified &

   output-to:"My Report.txt"