Scripting Reference

These are the script commands (in alphabetical order) as of version 2.1 Beta (Build 211):

ATTRIB BEEP COLLAPSE COMPARE COPY COPYTO CRITERIA DELETE EXPAND FILE-REPORT FILTER FOLDER-REPORT LOAD LOG MOVE OPTION RENAME REPORT SELECT SNAPSHOT SYNC TOUCH

ATTRIB

Usage:

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

Sets (+) or clears (-) the attribute set of items in the current selection. An attribute set can include archive (a), system (s), hidden (h), and readonly (r) attributes.

Examples:

attrib +h
attrib +sh -a

BEEP

Usage:

beep

Beeps the PC speaker.

COLLAPSE

Usage:

collapse all
collapse <path> [<path> [...]]

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

Example:

collapse "Folder 1" Folder2\SubFolder

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 (lt->rt|rt->lt)

Copies the selected files/folders in the direction indicated.

COPYTO

Usage:

copyto (lt|rt|all) [path:(relative|base|none)] <path>

Copies the selected files/folders on the specified side to the specified path using the path option. By default, path:none is used.

CRITERIA

Usage:

criteria [attrib:<attrib set>] [version] \
         [timestamp[:[#sec][;IgnoreDST]]] \
         [size|CRC|binary|rules-based] \
         [timezone:(ignore|(lt|rt)(+|-)<0..12>)]

Sets all comparison criteria settings.

attrib enables comparisons of the specified attribute set.
version enables comparisons of version information common in exes and dlls.
timestamp enables timestamp comparisons.
- #sec considers differences within a tolerance of seconds as matches.
- IgnoreDST 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.

Example:

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

DELETE

Usage:

delete [recyclebin=(yes|no)] (lt|rt|all)

Deletes the currently selected files/folders on the specified side(s).

EXPAND

Usage:

expand all
expand <path> [<path> [...]]

Expands all folders or folders with specified paths. Paths are relative to the base folder and can not have wildcards. Folders must be expanded in order for their contents to be used by other commands, like select.

FILE-REPORT

Usage:

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

Generates a file comparison report of the currently selected files.

layout controls the reports appearance, and can be any of over-under, side-by-side, composite, patch, statistics, or xml.
options is optional, and is used differently for each layout.
- ignore-unimportant treats differences in unimportant text as matches and is available in all layouts.
- display-all, display-mismatches, display-context, or display-matches can be used to control which lines of the comparison are included in the report and are available in all layouts except patch and statistics. By default, display-all is used.
- line-numbers includes line numbers in the side-by-side layout.
- stats-descriptive or stats-tabular (CSV) formats are available in the statistics layout. By default, stats-descriptive is used.
- patch-standard, patch-context, patch-unified, or patch-classic formats are available in the patch layout. By default, patch-standard is used.

Both file-report and folder-report must include information on where the report should be sent, and may include additional information on the output format.

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.
- print-color or print-mono color schemes are available for printer output.
- print-portrait or print-landscape orientations are available for printer output. By default, print-portrait is used.
- wrap-none, wrap-character, or wrap-word word wrapping are available for printer output for file-report only. By default, wrap-none is used.
- html-color, html-mono, or html-custom=<filename> stylesheets are available for clipboard and file outputs. If html-custom is used it should include a URL or path, which will be used as the HTML's external style sheet.

Examples:

file-report layout:over-under options:display-context output-to:printer &
            output-options:print-color,wrap-word
file-report layout:patch options:ignore-all,patch-unified &
            output-to:"reports\report.txt"

FILTER

Usage:

filter <file masks>
filter cutoff:([<|>](<timestamp>|#[days])|none)
filter attrib:((+|-)<attrib set>|none)

Controls which folders and types of files that are compared using name filtering (file masks), date filtering (cutoff), or other filtering (attrib).

Name filters include and exclude files and folders based on their names and paths. Multiple masks can be 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 (#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:"01/01/2001 12:00pm"). Remember to use quotation marks (" ") whenever a term contains a space.
attrib limits the comparison to files which have an included attribute (+) and don't have an excluded attribute (-). none can be used to remove attribute filtering.

Examples:

filter "*.pas;*.dpr;*.dfm"
filter cutoff:<7days
filter cutoff:>"Jan 1, 2001"
filter cutoff:"01/01/2001 12:00pm"
filter attrib:-sh
filter "*.txt;-Recycle Bin\" attrib:+r

FOLDER-REPORT

Usage:

folder-report layout:<layout> [options:<options>] \
              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 reports appearance, and can be side-by-side, summary, or xml.
options is optional.
- Display 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.
- Optional columns can be included in the report by using the flags column-version, column-size, column-crc, column-timestamp, and column-attributes. By default, column-size and column-timestamp are included. column-none can be used by itself to clear the default columns.
output-to and output-options arguments are documented under file-report.

Examples:

folder-report layout:side-by-side,column-size,column-version,column-timestamp &
              output-to:clipboard output-options:html-color
folder-report layout:xml output-to:"C:\Folder Report.xml"

LOAD

Usage:

load <session>
load <left path> [<right path>]
load <default>

Loads the specified session, the specified base folders, or the Default Session 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, to be used.
Loading base folders uses the currently active settings. By default, the program defaults are used.

Examples:

load MySession
load c:\project x:\project

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 system folder.

MOVE

Usage:

move (lt->rt|rt->lt)

Moves the selected files/folders in the direction specified.

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.

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 Rename" is performed.

REPORT (deprecated)

This command has been deprecated and will not be updated to support new reporting features. Use FILE-REPORT or FOLDER-REPORT instead.

Usage:

report format:<format> \
       output:(<printer>|<clipboard>|<filename>)[;<options>] \
       [<filename 1> [<filename 2>]]

Produces a Folder Comparison report or a File Differences report in the specified format and sends it to the output location specified. Folder Comparison reports will always use the currently loaded base folders. File Difference reports will report on the files specified, otherwise it will report on all currently selected files.

The report can be directed to the default printer, the clipboard, or to a specific file. <printer> and <clipboard> are keywords, including the angle brackets.

The options for output:<printer> are:
p portrait mode (default)
l landscape mode
c color output

For output:<clipboard> or output:<filename>, use the h option to specify HTML output.

Examples:

load "C:\Website" "ftp://mywebsite.com/"
report format:50n output:Report.html;h
report format:03d output:<printer> C:\Sample\File1.txt C:\Sample\File2.txt

SELECT

Usage:

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

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. A selection mask has the format, [<side>.][<difference>.]<item>.

A side (left or lt, right or rt, all) limits the selection to the specified side. By default, all is used.
A difference (exact, diff, newer, older, orphan, all) limits the selection based on results of comparison. diff refers to differences in criteria other than timestamps. Use newer or older instead. Folders must contain only the specified result type to be affected. By default, all is used.
An item (files, folders, all) limits the selection to files, folders, or both.

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

Examples:

select lt.files rt.orphan.folders
select all

SNAPSHOT

Usage:

snapshot [save-crc][save-version][expand-archives][no-filters] \
         lt|rt|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.
no-filters stores all files regardless of the active filename filters.
lt, rt, and path indicate which folder is stored. lt and rt 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.
- If 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.
- If 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_2000-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 lt output:"Home Copy.bcss"

SYNC

Usage:

sync [visible][create-empty] (update|mirror):(lt->rt|rt->lt|all)

Uses the Synchronize Folders engine to update a pair of folders. 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, and orphans in the destination are deleted. The all direction doesn't apply in this context, and is not valid.

Example:

sync create-empty mirror:lt->rt

TOUCH

Usage:

touch (lt->rt|rt->lt)
touch (lt|rt|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.