Differences
This shows you the differences between the selected revisions of the page.
| file_mask 2014-09-22 | file_mask 2023-05-24 (current) | ||
| Line 2: | Line 2: | ||
| To use the following features of WinSCP you need to specify a mask (wildcard) to select files (or other things): | To use the following features of WinSCP you need to specify a mask (wildcard) to select files (or other things): | ||
| * Text file mask for [[transfer_mode|text mode transfers]]. | * Text file mask for [[transfer_mode|text mode transfers]]. | ||
| - | * [[ui_transfer_custom#other_options|File mask]] for transfers and synchronization. | + | * [[ui_transfer_custom#other|File mask]] for transfers and synchronization. |
| * [[ui_select|Selecting/unselecting files]] by file mask. | * [[ui_select|Selecting/unselecting files]] by file mask. | ||
| * [[ui_file_panel#filtering|Filtering files]] in file panel. | * [[ui_file_panel#filtering|Filtering files]] in file panel. | ||
| Line 8: | Line 8: | ||
| * Defining [[ui_editor_preferences#autoselection|autoselection mask for editors]]. | * Defining [[ui_editor_preferences#autoselection|autoselection mask for editors]]. | ||
| * Various [[scripting#commands|script commands]]. | * Various [[scripting#commands|script commands]]. | ||
| - | * ''[[library_transferoptions|TransferOptions.FileMask]]'' in [[library|.NET assembly]]. | + | * ''[[library_transferoptions#filemask|TransferOptions.FileMask]]'' in [[library|.NET assembly]]. |
| You can use [[ui_editmask|File Mask dialog]] to help you with assembling the mask. | You can use [[ui_editmask|File Mask dialog]] to help you with assembling the mask. | ||
| - | ===== Basic Syntax ===== | + | ===== [[basic]] Basic Syntax ===== |
| When specifying the mask you can use following patterns: | When specifying the mask you can use following patterns: | ||
| Line 24: | Line 24: | ||
| To escape character with special meaning in patterns (''*?['') surround it by set pattern, e.g. ''filewithstar[*]''. | To escape character with special meaning in patterns (''*?['') surround it by set pattern, e.g. ''filewithstar[*]''. | ||
| + | |||
| + | The file masks are case insensitive. | ||
| ===== [[size_time]] Size and Time Constraints ===== | ===== [[size_time]] Size and Time Constraints ===== | ||
| Line 29: | Line 31: | ||
| ^ Pattern ^ Meaning ^ Example ^ | ^ Pattern ^ Meaning ^ Example ^ | ||
| - | | ''>size[KMG]'' | Matches files larger than ''size''. Following units can be used: ''K'' (Kilobyte), ''M'' (Megabyte) or ''G'' (Gigabyte). | ''*.bin>1M'' | | + | | ''>size[KMG]'' | Matches files larger than ''size''. \\ Note that directories are considered to have a zero size. \\ Following units can be used: ''K'' (Kilobyte), ''M'' (Megabyte) or ''G'' (Gigabyte). | ''*.bin>1M'' | |
| | ''<size[KMG]'' | Matches files smaller than ''size''. | ''<1G'' | | | ''<size[KMG]'' | Matches files smaller than ''size''. | ''<1G'' | | ||
| - | | ''>yyyy-mm-dd[·hh:mm[:ss]]'' ·| Matches files modified the last time after the date or time (i.e. "newer than"). | ''>2012-01-01'', ''>2012-02-29·08:47'' | | + | | ''>yyyy-mm-dd[ hh:mm[:ss]]'' | Matches files modified the last time after the date or time (i.e. "newer than"). | ''>2012-01-01'' \\ ''>2012-02-29 08:47'' | |
| - | | ''>time[YDHNS]'' | Matches files modified the last time within specified interval (i.e. "newer than"). One of the following units must be used: ''Y'' (years), ''D'' (days), ''H'' (hours), ''N'' (minutes) or ''S'' (seconds). | ''*.doc>1Y'' | | + | | ''>time[YDHNS][S]'' | Matches files modified the last time within specified interval (i.e. "newer than"). \\ Cannot be used for directories. \\ One of the following units must be used: ''Y'' (years), ''D'' (days), ''H'' (hours), ''N'' (minutes) or ''S'' (seconds). \\ Optional ''S'' suffix denotes rounding the time before the interval to the start of the interval unit. For example, ''2DS'' refers to the start (midnight) of the day before yesterday. ''0HS'' refers to the start of the current hour. Keywords ''==today=='' and ''==yesterday=='' can be used instead of ''0DS'' and ''1DS'', respectively. | ''*.doc>1Y'' \\ ''>2HS'' \\ ''>yesterday'' | |
| - | | ''<yyyy-mm-dd[·hh:mm[:ss]]'' ·| Matches files modified the last time before the date or time (i.e. "older than"). | ''*.doc<2012-02-29·08:54:21'' | | + | | ''<yyyy-mm-dd[ hh:mm[:ss]]'' | Matches files modified the last time before the date or time (i.e. "older than"). | ''*.doc<2012-02-29 08:54:21'' | |
| - | | ''<time[YDHNS]'' | Matches files modified the last time before specified interval (i.e. "older than"). | ''<60D'' | | + | | ''<time[YDHNS][S]'' | Matches files modified the last time before specified interval (i.e. "older than"). | ''<60D'' | |
| It is also possible to use operators ''>='' and ''%%<=%%''. | It is also possible to use operators ''>='' and ''%%<=%%''. | ||
| Line 40: | Line 42: | ||
| To escape an operator character (''<>''), double it, e.g. ''filewith%%<<%%lessthan''. | To escape an operator character (''<>''), double it, e.g. ''filewith%%<<%%lessthan''. | ||
| - | ===== Combining Masks ===== | + | To combine constraints, append one after another, without any separators (or use spaces). E.g. to select all ''.doc'' files created in 2013: ''%%*.doc>=2013-01-01<=2013-12-31%%''. |
| - | In most contexts, you can combine several masks using semicolon ('';'') or comma ('',''). You cannot use this in source parameters of [[scripting#commands|script commands]] and .NET assembly methods.((Note that this restriction does not apply to ''-filemask'' switch in scripting and ''[[library_transferoptions|TransferOptions.FileMask]]'' in .NET assembly.)) | + | |
| + | Note that if your constraint contains spaces (particularly constraint with date and time), to use it in [[scripting]], you need to enclose whole mask to double-quotes. | ||
| + | |||
| + | ===== [[combining]] Combining Masks ===== | ||
| + | In most contexts, you can combine several masks using semicolon ('';'') or comma ('',''). You cannot use this in source parameters of [[scripting#commands|script commands]] and .NET assembly methods.((Note that this restriction does not apply to ''-filemask'' switch in scripting and ''[[library_transferoptions#filemask|TransferOptions.FileMask]]'' in .NET assembly.)) | ||
| For example following mask includes all JPG and GIF images: ''*.jpg; *.gif''. | For example following mask includes all JPG and GIF images: ''*.jpg; *.gif''. | ||
| Line 48: | Line 54: | ||
| ===== [[include_exclude]] Include and Exclude Masks ===== | ===== [[include_exclude]] Include and Exclude Masks ===== | ||
| - | Mask can combine include and exclude mask separated by pipe (''|''). | + | Mask can combine include and exclude mask separated by pipe (''|''). You cannot use this in source parameters of [[scripting#commands|script commands]] and .NET assembly methods.((Note that this restriction does not apply to ''-filemask'' switch in scripting and ''[[library_transferoptions#filemask|TransferOptions.FileMask]]'' in .NET assembly.)) |
| For example following mask includes all JPG and GIF images, but excludes those starting with ''2010'' and ''2011'': ''*.jpg; *.gif | 2010*; 2011*''. | For example following mask includes all JPG and GIF images, but excludes those starting with ''2010'' and ''2011'': ''*.jpg; *.gif | 2010*; 2011*''. | ||
| Line 54: | Line 60: | ||
| Both include and exclude part can be empty, denoting that everything is included or nothing is excluded, respectively. When include part is empty, masks starts with pipe straight away. When exclude part is empty, you can omit the trailing pipe. | Both include and exclude part can be empty, denoting that everything is included or nothing is excluded, respectively. When include part is empty, masks starts with pipe straight away. When exclude part is empty, you can omit the trailing pipe. | ||
| - | Exclude mask takes precedence over include mask. I.e. when the same file is matched by both the exclude and include mask, it is excluded. | + | Exclude mask takes precedence over include mask. I.e. when the same file is matched by both the exclude and include mask, it is excluded. On the other hand, using an include mask effectively excludes all non included files and folders. |
| To escape pipe character double it, e.g. ''filewith||pipe''. | To escape pipe character double it, e.g. ''filewith||pipe''. | ||
| Line 63: | Line 69: | ||
| Note that when using [[ui_editmask|File Mask dialog]], the trailing slash for directory masks is appended automatically. | Note that when using [[ui_editmask|File Mask dialog]], the trailing slash for directory masks is appended automatically. | ||
| - | To make operation non-recursive use exclude mask ''*/''((Full inline file mask syntax, in case there's no other mask involved, is ''|*/'', where the ''|'' denotes a start of an [[#include_exclude|exclude mask]].)). | + | To make operation non-recursive use exclude mask ''*/''.((Full inline file mask syntax, in case there's no other mask involved, is ''|*/'', where the ''|'' denotes a start of an [[#include_exclude|exclude mask]].)) |
| Directory masks are recursive. E.g. mask ''images/'' matches directories ''/home/martin/images/'' as well as ''/home/martin/images/avatars/''. | Directory masks are recursive. E.g. mask ''images/'' matches directories ''/home/martin/images/'' as well as ''/home/martin/images/avatars/''. | ||
| - | ===== Path Mask ===== | + | During transfer and [[task_synchronize_full|synchronization]], files and directories are processed recursively. When a directory is excluded, subdirectories and files contained in the excluded directory are not even evaluated against file masks. They are excluded along with its container directory. |
| - | When a mask selects files and it makes sense to select them based on directory, you can extend the mask with a path mask. You should separate the path mask from the filename mask by a slash. For example mask ''/home/martinp/*.txt'' matches all text files within the directory. To match all text files within subtree, use mask ''/home/martinp/*.txt; /home/martinp/*/*.txt''((Simpler, but less precise, form would be ''/home/martinp*/*.txt'')). | + | |
| + | ===== [[path]] Path Mask ===== | ||
| + | When a mask selects files and it makes sense to select them based on directory, you can extend the mask with a path mask. You should separate the path mask from the filename mask by a slash. For example mask ''/home/martinp/*.txt'' matches all text files within the directory. To match all text files within subtree, use mask ''/home/martinp/*.txt; /home/martinp/*/*.txt''.((Simpler, but less precise, form would be ''/home/martinp*/*.txt''.)) | ||
| The path mask is matched against full path, i.e. not against path relative path to a root of file transfer or synchronization. E.g. mask ''public_html/wiki/'' does not match ''/home/martinp/public_html/wiki'' directory, even if the root of file transfer or synchronization is ''/home/martinp''. Partial path mask that matches an absolute path may look like ''*/public_html/wiki/''. | The path mask is matched against full path, i.e. not against path relative path to a root of file transfer or synchronization. E.g. mask ''public_html/wiki/'' does not match ''/home/martinp/public_html/wiki'' directory, even if the root of file transfer or synchronization is ''/home/martinp''. Partial path mask that matches an absolute path may look like ''*/public_html/wiki/''. | ||
| For a partial path mask it makes no difference whether you use back (''\'') or forward slashes (''/''); the mask will always work for both local and remote paths. For example, a mask ''*/public_html/*.bak'' will match backup files both in ''D:\Documents\public_html\'' and ''/home/martinp/public_html/''. | For a partial path mask it makes no difference whether you use back (''\'') or forward slashes (''/''); the mask will always work for both local and remote paths. For example, a mask ''*/public_html/*.bak'' will match backup files both in ''D:\Documents\public_html\'' and ''/home/martinp/public_html/''. | ||
| + | |||
| + | Paths starting with a dot followed by a slash (''./'' or ''.\'') are matched from the root of the operation (such as file transfer or synchronization). For example, when uploading files and folders from local path ''D:\Documents\public_html\'' to remote path ''/home/martinp/public_html/'', mask ''.\data\*.txt'' matches ''*.txt'' files in ''D:\Documents\public_html\data\''. | ||
| You can also specify full path to a specific file or directory, both local and remote. For example if you want to match only a specific ''.csv'' directory, not all, use ''/home/martinp/data/.csv/'' instead of ''.csv/''. | You can also specify full path to a specific file or directory, both local and remote. For example if you want to match only a specific ''.csv'' directory, not all, use ''/home/martinp/data/.csv/'' instead of ''.csv/''. | ||
| - | ===== Exceptions ===== | + | The full path mask matches a local or a remote paths only, depending on the syntax used.((Paths starting with drive letter and colon match local paths only. Paths starting with slash match remote path only. Type of slashes does not matter.)) This matters for [[task_synchronize|synchronization]] particularly. For exclude masks, you may need to use a separate full path mask for both local and remote path. For include masks, using a full path mask does not make sense with synchronization, as it effectively excludes all files on the other side of the synchronization, breaking it. In general, use partial path masks with the synchronization. |
| - | For convenience, masks ''*.*'' and ''*.'' are exceptions matching any file and any file without an extension, respectively, even if its name does not include any dot. | + | |
| + | ===== [[exceptions]] Exceptions ===== | ||
| + | For convenience, mask ''*.*'' is an exception matching any file or directory, even if its name does not include any dot. On the contrary, mask ''*.'' matches any file or directory without an extension. | ||
| + | ===== [[emptysubfolder]] Subfolders with All Files Excluded ===== | ||
| + | Excluding all files within a subfolder from transfer or synchronization does not exclude the subfolder itself. As a result an empty subfolder is created in the target. To prevent that, use the [[ui_transfer_custom#other|//Exclude empty directories// transfer setting]]. In [[scripting]] or [[library|.NET assembly]], use the [[rawtransfersettings#excludeemptydirectories|''ExcludeEmptyDirectories'' raw transfer setting]]. | ||