Differences
This shows you the differences between the selected revisions of the page.
| scriptcommand_put 2014-04-30 | scriptcommand_put 2024-04-09 (current) | ||
| Line 1: | Line 1: | ||
| - | ====== put ====== | + | ====== put command ====== |
| [[task_upload|Uploads]] one or more files from local directory to remote directory. | [[task_upload|Uploads]] one or more files from local directory to remote directory. | ||
| Line 6: | Line 6: | ||
| put <file> [ [ <file2> ... ] <directory>/[ <newname> ] ] | put <file> [ [ <file2> ... ] <directory>/[ <newname> ] ] | ||
| - | ===== Remarks ===== | + | ===== [[remarks]] Remarks ===== |
| - | If only one parameter is specified uploads the file to remote working directory. If more parameters are specified, all except the last one specify set of files to upload. The last parameter specifies target remote directory and optionally [[operation_mask|operation mask]] to store file(s) under different name. Destination directory must end with slash. Filename can be replaced with Windows wildcard ((Windows wildcard supports ''*'' and ''?'' only. It does not support all the features of [[file_mask|file masks]].)) to select multiple files. To upload more files to current working directory use ''./'' as the last parameter. | + | If only one parameter is specified, uploads the file to remote working directory. If more parameters are specified, all except the last one specify set of files to upload. Filename can be replaced with Windows wildcard ((The Windows wildcard supports ''*'' and ''?'' only. If you want to use a full syntax of [[file_mask|file masks]], use a ''[[#filemask|-filemask]]'' switch.)) to select multiple files. To upload all files in a directory, use mask ''*''. |
| - | When specific file name is used, command fails when the file does not exist. When wildcard is used, command succeeds, without doing anything, if the wildcard does not match any file. | + | The last parameter specifies ==target== remote directory and optionally [[operation_mask|operation mask]] to store file(s) under different name. Target directory must end with slash. To upload more files to current working directory use ''./'' as the last parameter. |
| + | |||
| + | With the [[commandline#stdin|''/stdin'' command-line switch]], ''-'' can be used as a source to ==stream== the [[executables#redirection|standard input of ''winscp.com'']] to remote server. Streaming is supported with the [[sftp|SFTP]] and [[ftp|FTP]] protocols only. | ||
| + | |||
| + | When specific file name is used, command fails when the file does not exist. When wildcard is used, command succeeds, without doing anything, if the wildcard does not match any file, by default (you can change this using ''[[scriptcommand_option#failonnomatch|option failonnomatch on]]'' command). | ||
| + | |||
| + | You can have WinSCP [[guide_automation#generating|generate a code template]] for ''put'' for you. | ||
| See also ''[[scriptcommand_synchronize|synchronize]]'', if you need to transfer modified files only. | See also ''[[scriptcommand_synchronize|synchronize]]'', if you need to transfer modified files only. | ||
| Line 16: | Line 22: | ||
| Switches: | Switches: | ||
| ^ Switch ^ Description ^ | ^ Switch ^ Description ^ | ||
| - | | ''-delete'' | Delete source local file(s) after transfer. | | + | | ''-==delete=='' | Delete source local file(s) after a successful transfer. | |
| - | | ''-resume'' | Automatically resume transfer if possible·((To be used for single file transfers only. It does not skip transfer of fully transferred files.)) ([[SFTP]] and [[FTP]] protocols only). Cannot be combined with ''-append''. | | + | | ''-==latest=='' | Uploads the latest file from the files selected by the ''file'', ''file2'' ... parameters (typically [[file_mask|file masks]]) only. | |
| - | | ''-append'' | Append source file to the end of target file ([[sftp|SFTP protocol]] only). Cannot be combined with ''-resume''. | | + | | ''-==resume=='' | Automatically resume transfer if possible.((Applies for individual files transfers only. It does not skip transfer of fully transferred files. For that, combine the switch with ''[[#neweronly|-neweronly]]''.)) \\ [[SFTP]] and [[FTP]] protocols only. Cannot be combined with ''[[#append|-append]]''. Has no effect when streaming (''-'' source). | |
| - | | ''-preservetime'' | Preserve timestamp | | + | | ''-==append=='' | Append source file to the end of target file. \\ [[sftp|SFTP protocol]] only. Cannot be combined with ''[[#resume|-resume]]''. | |
| - | | ''-nopreservetime'' | Do not preserve timestamp | | + | | ''-==preservetime=='' | Preserve timestamp. | |
| - | | ''-permissions=<mode>'' | Set permissions ([[SFTP]] and [[SCP]] protocols only) | | + | | ''-==nopreservetime=='' | Do not preserve timestamp. | |
| - | | ''-nopermissions'' | Keep default permissions | | + | | ''-==permissions===<mode>'' | Set permissions ([[SFTP]] and [[SCP]] protocols only). \\ Has no effect when streaming (''-'' source). | |
| - | | ''-speed=<kibps>'' ······| Limit transfer speed | | + | | ''-==nopermissions=='' | Keep default permissions. | |
| - | | ''-transfer=<mode>'' | ''%%binary|ascii|automatic%%'' \\ [[transfer_mode|Transfer mode]]: binary, ascii (text), automatic (by extension). | | + | | ''-==speed===<kbps>'' ·······| Limit transfer speed (in KB/s). | |
| - | | ''-filemask=<mask>'' | ''%%<mask>[;<mask2>...]%%'' \\ Sets [[file_mask|file mask]]. | | + | | ''-==transfer===<mode>'' | ''%%binary|ascii|automatic%%'' \\ [[transfer_mode|Transfer mode]]: binary, ascii (text), automatic (by extension). | |
| - | | ''-resumesupport=·<state>'' | ''%%on|off|<threshold>%%'' \\ Configures [[resume#automatic|automatic resume/transfer to temporary filename]]. | | + | | ''-==filemask===<mask>'' | ''%%<mask>[;<mask2>...]%%'' \\ Sets [[file_mask|file mask]]. | |
| + | | ''-==resumesupport===<state>'' | ''%%on|off|<threshold>%%'' \\ Configures [[resume#automatic|automatic resume/transfer to temporary filename]]. | | ||
| + | | ''-==neweronly=='' | Transfer new and updated files only. See also ''[[scriptcommand_synchronize|synchronize]]'' command. | | ||
| + | | ''-==rawtransfersettings== setting1=value1 setting2=value2 ...'' | Allows configuring any transfer settings using [[rawtransfersettings|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. | | ||
| Aliases: ''send'', ''mput'' | Aliases: ''send'', ''mput'' | ||
| - | Effective [[scriptcommand_option|options]]: ''confirm'', ''reconnecttime'' | + | Effective [[scriptcommand_option|options]]: ''[[scriptcommand_option#confirm|confirm]]'', ''[[scriptcommand_option#reconnecttime|reconnecttime]]'', ''[[scriptcommand_option#failonnomatch|failonnomatch]]'' |
| - | XML log elements: ''[[logging_xml#upload|upload]]'', ''[[logging_xml#chmod|chmod]]'' (with ''-permissions''), ''[[logging_xml#touch|touch]]'' (with ''-preservetime'') | + | XML log elements: ''[[logging_xml#upload|upload]]'', ''[[logging_xml#mkdir|mkdir]]'', ''[[logging_xml#chmod|chmod]]'' (with ''[[#permissions|-permissions]]''), ''[[logging_xml#touch|touch]]'' (with ''[[#preservetime|-preservetime]]'') |
| ===== Examples ===== | ===== Examples ===== | ||
| Line 54: | Line 63: | ||
| </code> | </code> | ||
| - | ===== Converting to .NET Assembly ===== | + | ===== [[net]] Converting to .NET Assembly ===== |
| When [[library_from_script|converting script to .NET Assembly]], map ''put'' command to ''[[library_session_putfiles|Session.PutFiles]]'' method. | When [[library_from_script|converting script to .NET Assembly]], map ''put'' command to ''[[library_session_putfiles|Session.PutFiles]]'' method. | ||
| Line 62: | Line 71: | ||
| ^ Switch ^ Mapping ^ | ^ Switch ^ Mapping ^ | ||
| | ''-delete'' | Value ''true'' (''$True'' in PowerShell) for method parameter ''remove''. | | | ''-delete'' | Value ''true'' (''$True'' in PowerShell) for method parameter ''remove''. | | ||
| - | | ''-resume'' | Not supported. | | + | | ''-latest'' | See [[script_upload_most_recent_file|*]]. | |
| - | | ''-append'' ·············| Not supported. | | + | | ''-resume'' \\ ''-append'' \\ ''-preservetime'' \\ ''-nopreservetime'' \\ ''-permissions'' \\ ''-nopermissions'' \\ ''-transfer'' \\ ''-filemask'' \\ ''-resumesupport'' \\ ''-speed=<kbps>'' | [[library_from_script_transfer_settings|Converting transfer settings scripting switches]] to .NET assembly class ''TransferSettings''. | |
| - | | ''-preservetime'' \\ ''-nopreservetime'' \\ ''-permissions'' \\ ''-nopermissions'' \\ ''-transfer'' \\ ''-filemask'' \\ ''-resumesupport'' | [[library_from_script_transfer_settings|Converting transfer settings scripting switches]] to .NET assembly class ''TransferSettings''. | | + | | ''-neweronly'' | Not supported. Use ''[[library_session_synchronizedirectories|Session.SynchronizeDirectories]]'' instead. | |
| - | | ''-speed=<kibps>'' | Not supported. | | + | |
| - | To emulate ''[[scriptcommand_option|option batch abort]]'' mode, call ''[[library_operationresultbase|TransferOperationResult.Check]]'' on method's result. See also [[library_session#results|Capturing results of operations]]. | + | To emulate the ([[scripting#using_scripting|default]]) ''[[scriptcommand_option#batch|option batch abort]]'' mode, call ''[[library_operationresultbase|TransferOperationResult.Check]]'' on method's result. See also [[library_session#results|Capturing results of operations]]. |
| For example, following script snippet: | For example, following script snippet: | ||
| <code winscp> | <code winscp> | ||
| - | option batch abort | ||
| - | ... | ||
| cd /home/martinp | cd /home/martinp | ||
| lcd d:\ | lcd d:\ | ||
| Line 89: | Line 95: | ||
| $transferOptions.ResumeSupport.State = [WinSCP.TransferResumeSupportState]::Off | $transferOptions.ResumeSupport.State = [WinSCP.TransferResumeSupportState]::Off | ||
| # Absolute paths + $True for -delete + Two calls for two source parameters | # Absolute paths + $True for -delete + Two calls for two source parameters | ||
| - | # + calling Check on result to emulate "option batch abort" | + | # + calling Check on result to emulate the (default) "option batch abort" mode |
| $session.PutFiles("d:\*.txt", "/home/martinp/web/", $True, $transferOptions).Check() | $session.PutFiles("d:\*.txt", "/home/martinp/web/", $True, $transferOptions).Check() | ||
| $session.PutFiles("d:\*.xml", "/home/martinp/web/", $True, $transferOptions).Check() | $session.PutFiles("d:\*.xml", "/home/martinp/web/", $True, $transferOptions).Check() | ||
| </code> | </code> | ||