synchronize command

Synchronizes content of a local directory with a remote one or vice versa or mutually.



synchronize local|remote|both [ <local directory> [ <remote directory> ] ]


When the first parameter is local, changes from remote directory are applied to local directory. When the first parameter is remote, changes from the local directory are applied to the remote directory. When the first parameter is both, both local and remote directories can be modified.

When directories are not specified, current working directories are synchronized.

Note: Overwrite confirmations are always off for the command.


Switch Description
-preview Preview changes only, do not synchronize. Transfer settings switches -permissions, -nopermissions, -speed, -transfer and -resumesupport have no effect.
-delete Delete obsolete files. Ignored for both mode.
-mirror Mirror mode (synchronize also older files). Ignored for both mode.
-criteria=<criteria> Comparison criteria. A comma-separated list of any of time, size and checksum, or none. For backward compatibility, either is an alias to time,size. Ignored for both mode.
-preservetime Preserve timestamp. Enforced by default unless -criteria lacks time.
-nopreservetime Do not preserve timestamp. Ignored unless -criteria lacks time.
-permissions=<mode> Set permissions (SFTP and SCP protocols only).
-nopermissions Keep default permissions.
-speed=<kbps> Limit transfer speed (in KB/s).
-transfer=<mode> binary|ascii|automatic
Transfer mode: binary, ascii (text), automatic (by extension).
-filemask=<mask> <mask>[;<mask2>...]
Sets file mask.
-resumesupport=<state> on|off|<threshold>
Configures automatic resume/transfer to temporary filename.
-rawtransfersettings setting1=value1 setting2=value2 Allows configuring any transfer settings using raw format as in an INI file. E.g. to enable preserving of directory timestamps, use -rawtransfersettings PreserveTimeDirs=1. The switch should come only after other parameters.


Effective options: reconnecttime, failonnomatch

XML log elements: download (with local or both), upload (with remote or both), mkdir, touch (with remote or both), chmod (with remote or both and -permissions), rm (with remote and -delete)


synchronize both
synchronize remote -delete d:\www /home/martin/public_html
synchronize both -filemask="|*.bak; *.tmp"

Converting to .NET Assembly

When converting script to .NET Assembly, map synchronize command to Session.SynchronizeDirectories method.

Parameters mapping: Command parameter local|remote|both maps to method parameter mode, with values SynchronizationMode.Local, SynchronizationMode.Remote and SynchronizationMode.Both, respectively (Enumeration syntax in PowerShell is like [WinSCP.SynchronizationMode]::Local). Command parameter local directory maps to method parameter localPath. Command parameter remote directory maps to method parameter remotePath. You have to convert relative paths to absolute paths.

Switches mapping:

Switch Mapping
-preview Use Session.CompareDirectories method instead of Session.SynchronizeDirectories.
-delete Value true ($True in PowerShell) for method parameter removeFiles.
-mirror Value true ($True) for method parameter mirror.
-criteria Set method parameter criteria. Use SynchronizationCriteria.Time for time, SynchronizationCriteria.Size for size, SynchronizationCriteria.Checksum for checksum and SynchronizationCriteria.None for none.
Enumeration syntax in PowerShell is like [WinSCP.SynchronizationCriteria]::Time.
Converting transfer settings scripting switches to .NET assembly class TransferSettings.

To emulate the (default) option batch abort mode, call TransferOperationResult.Check on method’s result. See also Capturing results of operations.

For example, following script snippet:

synchronize both d:\www /home/martin/public_html


maps to following PowerShell code:

$synchronizationResult =
        [WinSCP.SynchronizationMode]::Both, "d:\www", "/home/martin/public_html", $False)
# Throw on any error to emulate the (default) "option batch abort" mode

Last modified: by martin