Differences
This shows you the differences between the selected revisions of the page.
| scriptcommand_get 2013-04-15 | scriptcommand_get 2023-09-12 (current) | ||
| Line 1: | Line 1: | ||
| - | ====== get ====== | + | ====== get command ====== |
| [[task_download|Downloads]] one or more files from remote directory to local directory. | [[task_download|Downloads]] one or more files from remote directory to local directory. | ||
| + | |||
| + | ===== [[syntax]] Syntax ===== | ||
| get <file> [ [ <file2> ... ] <directory>\[ <newname> ] ] | get <file> [ [ <file2> ... ] <directory>\[ <newname> ] ] | ||
| - | Downloads one or more files from remote directory to local directory.·If only one parameter is specified downloads the file to local working directory. If more parameters are specified, all except the last one specify set of files to download. The last parameter specifies target local directory and optionally [[operation_mask|operation mask]] to store file(s) under different name. Destination directory must end with backslash. Filename can be replaced with [[file_mask|wildcard]] to select multiple files. To download more files to current working directory use ''.\'' as the last parameter. | + | ===== [[remarks]] Remarks ===== |
| + | |||
| + | Downloads one or more files from remote directory to local directory. | ||
| + | |||
| + | If only one parameter is specified, downloads the file to local working directory. If more parameters are specified, all except the last one specify set of files to download. Filename can be replaced with [[file_mask|wildcard]] to select multiple files. To download all files in a directory, use mask ''*''. | ||
| + | |||
| + | The last parameter specifies target local directory and optionally [[operation_mask|operation mask]] to store file(s) under different name. Target directory must end with backslash. To download more files to current working directory use ''.\'' as the last parameter. | ||
| + | |||
| + | With the [[commandline#stdout|''/stdout'' command-line switch]], ''-'' can be used as a target to ==stream== the contents of downloaded file(s) to the [[executables#redirection|standard output of ''winscp.com'']]. Streaming is supported with the [[sftp|SFTP]] and [[ftp|FTP]]. | ||
| + | |||
| + | 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 ''get'' for you. | ||
| See also ''[[scriptcommand_synchronize|synchronize]]'', if you need to transfer modified or non-existing files only. | See also ''[[scriptcommand_synchronize|synchronize]]'', if you need to transfer modified or non-existing files only. | ||
| Line 12: | Line 26: | ||
| Switches: | Switches: | ||
| ^ Switch ^ Description ^ | ^ Switch ^ Description ^ | ||
| - | | ''-delete'' | Delete source remote file(s) after transfer. | | + | | ''-==delete=='' | Delete source remote file(s) after a successful transfer. | |
| - | | ''-resume'' | Automatically resume transfer if possible·([[SFTP]] and [[FTP]] protocols only). Cannot be combined with ''-append''. | | + | | ''-==latest=='' | Download 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''.)) \\ [[SFTP]] and [[FTP]] protocols only. Cannot be combined with ''-append''. Has no effect when streaming (''-'' target). | |
| - | | ''-preservetime'' | Preserve timestamp | | + | | ''-==append=='' | Append source file to the end of target file. \\ [[sftp|SFTP protocol]] only. Cannot be combined with ''-resume''. Has no effect when streaming (''-'' target). | |
| - | | ''-nopreservetime'' | Do not preserve timestamp | | + | | ''-==preservetime=='' | Preserve timestamp. | |
| - | | ''-speed=<kibps>'' ······| Limit transfer speed | | + | | ''-==nopreservetime=='' | Do not preserve timestamp. | |
| - | | ''-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. | | ||
| - | 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#download|download]]'', ''[[logging_xml#rm|rm]]'' (with ''-delete'') | + | XML log elements: ''[[logging_xml#download|download]]'', ''[[logging_xml#rm|rm]]'' (with ''[[#delete|-delete]]'') |
| - | ===== Examples ===== | + | ===== [[examples]] Examples ===== |
| <code winscp> | <code winscp> | ||
| get index.html | get index.html | ||
| + | </code> | ||
| + | <code winscp> | ||
| get -delete index.html about.html .\ | get -delete index.html about.html .\ | ||
| + | </code> | ||
| + | <code winscp> | ||
| get index.html about.html d:\www\ | get index.html about.html d:\www\ | ||
| + | </code> | ||
| + | <code winscp> | ||
| get public_html/index.html d:\www\about.* | get public_html/index.html d:\www\about.* | ||
| + | </code> | ||
| + | <code winscp> | ||
| get *.html *.png d:\www\*.bak | get *.html *.png d:\www\*.bak | ||
| + | </code> | ||
| + | <code winscp> | ||
| get -filemask=*.html -resumesupport=on * | get -filemask=*.html -resumesupport=on * | ||
| </code> | </code> | ||
| + | ===== [[net]] Converting to .NET Assembly ===== | ||
| + | When [[library_from_script|converting script to .NET Assembly]], map ''get'' command to ''[[library_session_getfiles|Session.GetFiles]]'' method. | ||
| + | Parameters mapping: Command parameter ''file'' maps to method parameter ''remotePath''. When multiple source file parameters are used, you need to call ''Session.GetFiles'' multiple times. Command parameter ''directory\newname'' maps to method parameter ''localPath''. You have to [[library_from_script#paths|convert relative paths to absolute paths]]. | ||
| + | |||
| + | Switches mapping: | ||
| + | ^ Switch ^ Mapping ^ | ||
| + | | ''-delete'' | Value ''true'' (''$True'' in PowerShell) for method parameter ''remove''. | | ||
| + | | ''-latest'' | See [[script_download_most_recent_file|*]]. | | ||
| + | | ''-resume'' \\ ''-append'' \\ ''-preservetime'' \\ ''-nopreservetime'' \\ ''-transfer'' \\ ''-filemask'' \\ ''-resumesupport'' \\ ''-speed=<kbps>'' | [[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. | | ||
| + | |||
| + | To emulate the ([[scripting#using_scripting|default]]) ''[[scriptcommand_option|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: | ||
| + | |||
| + | <code winscp> | ||
| + | cd /home/martinp | ||
| + | lcd d:\ | ||
| + | ... | ||
| + | get -delete -filemask=*>1M -resumesupport=off *.txt *.xml web\ | ||
| + | </code> | ||
| + | |||
| + | maps to following [[library_powershell|PowerShell]] code: | ||
| + | |||
| + | <code powershell> | ||
| + | $transferOptions = New-Object WinSCP.TransferOptions | ||
| + | # -filemask=*>1M | ||
| + | $transferOptions.FileMask = "*>1M" | ||
| + | # -resumesupport=off | ||
| + | $transferOptions.ResumeSupport.State = [WinSCP.TransferResumeSupportState]::Off | ||
| + | # Absolute paths + $True for -delete + Two calls for two source parameters | ||
| + | # + calling Check on result to emulate the (default) "option batch abort" mode | ||
| + | $session.GetFiles("/home/martinp/*.txt", "d:\web\", $True, $transferOptions).Check() | ||
| + | $session.GetFiles("/home/martinp/*.xml", "d:\web\", $True, $transferOptions).Check() | ||
| + | </code> | ||