Documentation » Features »

Transfer Modes

As different platforms (operating systems) use different format of text files, many transfer protocols support special mode for transferring text files (called text or ASCII mode). In the mode the file is not only transferred, but also converted to format used by the target platform. The mode must not be used for binary files (including document files from modern text processors, like Microsoft Word), as they must be transferred without modification.

Available Modes
Server-side Text File Format
Editing Binary Files
Changing Transfer Mode
Additional Modifications
Transferring Large Text Files with SCP Protocol
Debugging Transfer Mode

Available Modes

WinSCP offers you the chance to select between Text and Binary transfer modes. It is set as one of the transfer settings.

WinSCP also has a special Automatic mode (default). With this mode WinSCP decides automatically about transfer mode for a particular file based on its filename (usually the file extension). The so-called text file mask can be configured in dialogs mentioned above. By default it includes HTML, TXT, PHP, XML, INI, C, CPP and other file types. You can modify the mask as you need. Files not matching the mask are transferred using Binary mode.

Server-side Text File Format

There are two options how to support text mode transfers. The first option is that the client (WinSCP) knows directly the text file format used by the server and converts the file to the format before transfer. The second option is that there is some in advance agreed canonical format to which the client converts the file before transfer and from which the server converts it (if necessary) after transfer to its own format.

The second option is more universal, but it is supported only by SFTP-4 and newer and FTP.1

The first option is used by WinSCP for SCP and SFTP-3 and older protocols. It this case the client (WinSCP) must directly know and support the server-side format. Generally there are plenty of text file formats, almost every platform has it own format. WinSCP supports two of the most used formats, Unix and Windows. You can select between them on Environment page of Advanced Site Settings dialog. As most SSH (SFTP and SCP) servers and many FTP servers are run on Unix system, generally you may leave the default Unix format.

WebDAV and S3 protocols do not allow selecting transfer mode.

Editing Binary Files

Learn how to edit remote binary file locally.

Changing Transfer Mode

The transfer mode is set as part of transfer settings.

Note that there are two predefined transfer settings presets, Text and Binary that may help you switching the mode.

Transfer mode configured in default transfer settings may be overridden with text mode when transferring file to/from editor.

To configure transfer mode in scripting, use -transfer switch of file transfer commands. In .NET assembly use TransferOptions.TransferMode.

Additional Modifications

WinSCP can perform additional modifications to the text files during transfer, if configured so. Particularly, it can remove UTF-8 byte order marks and eof-of-file marks from uploaded files with SFTP and SCP protocols. See Remove BOM and EOF marks transfer settings.

Transferring Large Text Files with SCP Protocol

Note that due to SCP protocol requirements WinSCP needs to know the size of converted text files before the transfer actually starts. For that reason with SCP protocol, the whole file is converted in memory before the transfer.

If the file is too large (not common for text files), you can run out of memory during conversion. So to transfer large text file, either force binary mode (if possible) or switch to SFTP protocol.