Differences
This shows you the differences between the selected revisions of the page.
| 2007-04-10 | 2023-05-24 (current) | ||
| 4.0 custom commands > last (martin) | 6.1 stable released (martin) | ||
| Line 2: | Line 2: | ||
| If there is a [[remote command]] you need to execute regularly and in particular if the command works with files, you may find custom commands useful. | If there is a [[remote command]] you need to execute regularly and in particular if the command works with files, you may find custom commands useful. | ||
| - | A custom command is a [[ui_pref_commands|predefined]] command which can contain several patterns that WinSCP replaces, for example, with names of files selected in a panel (see below). For example, the pre-defined custom command //Touch//, defined as ''touch "!"'', calls the ''touch'' command on every selected file in the remote panel. | + | A custom command is a [[ui_pref_commands|predefined]] command which can contain several patterns that WinSCP replaces, for example, with names of files selected in a panel (see below). For example, the pre-defined custom command //Touch//, defined as ''touch %%"!"%%'', calls the ''touch'' command on every selected file in the remote panel. |
| However you can have even custom commands without patterns, just to avoid typing the command again every time. | However you can have even custom commands without patterns, just to avoid typing the command again every time. | ||
| ===== [[types]] Types of Custom Commands ===== | ===== [[types]] Types of Custom Commands ===== | ||
| - | There are basically four types of custom commands: | + | There are basically these types of custom commands: |
| - | * Remote or local commands that does not work with files. These can be executed any time. | + | * Remote or local commands that do not work with files. These can be executed any time. |
| - | * Remote commands are executed on the remote servers with the remote files. These commands can modify the files. You need to have selected remote files first to execute the command. | + | * Remote commands that are executed on remote servers with remote files. These commands can modify the files. You must have remote files selected first in order to execute the command. |
| - | * Local commands are executed on the local machine with the remote files downloaded to [[temp_folders|temporary folder]]. It makes no sense for the command to modify the files, because they are not uploaded back after the command finishes. You need to have selected remote files first to execute the command. | + | * Local commands that are executed on the local machine with remote files downloaded to a [[temp_folders|temporary folder]]. You must have remote files selected first in order to execute the command. If the command modifies the files, the changes are uploaded to the server. |
| - | * Special type is local command that is executed both with local and remote files. This is particularly useful for running "diff" tools. This type is available only with [[ui_commander|Norton Commander interface]]. You can execute such command for set of remote files against the the same number or local files (once for each pair). Another option is to execute it for set of remote files against one local file (once for each remote file) and vice versa. | + | * Local commands that are executed on the local machine with paths to a remote files. Such commands will typically operate on the files over their own session (use ''!E'' or ''!S'' pattern to pass current session settings to the command). The command may use [[guide_custom_commands_automation|WinSCP .NET assembly or scripting]]. |
| + | * Local commands that work with local files. The command can work completely with selected local files only. Or it can for example process the local file somehow (e.g. compress them) and upload them to the remote server using own session (again, use the ''!E'' or ''!S'' pattern as mentioned previously). | ||
| + | * Special type is a local command that is executed with both local and remote files. This is particularly useful for running "diff" tools. This type is available only with the [[ui_commander|Commander interface]]. You can execute these commands on a set of remote files against the the same number of local files (once for each pair). Another option is to execute it on a set of remote files against one local file (once for each remote file) and vice versa. | ||
| ===== [[patterns]] Patterns Used in Custom Commands ===== | ===== [[patterns]] Patterns Used in Custom Commands ===== | ||
| You can use following patterns in your custom commands: | You can use following patterns in your custom commands: | ||
| - | ^ Pattern ^ Command Type ^ Descriptions ^ | + | ^ Pattern ^ Command Type ^ Description ^ |
| | ''!!'' | Any | Is replaced with exclamation mark (''!''). | | | ''!!'' | Any | Is replaced with exclamation mark (''!''). | | ||
| - | | ''!'' | Any | Name of file. Command with the pattern will be executed once for every selected file. In general it should be surrounded with quotes for the command to work with filenames containing spaces. Cannot be combined with pattern ''!&''. | | + | | ''!'' | Any | File path (a relative path to a root of an operation, when referring to remote file; an absolute path when referring to a local temporary copy of a remote file). Command with the pattern will be executed once for every selected file. In general it should be surrounded with quotes for the command to work with filenames containing spaces. Cannot be combined with pattern ''!&''. | |
| - | | ''!&'' | Any | Quoted, space-delimited list of files. Command with the pattern will be executed only once for all selected files. Cannot be combined with pattern ''!'' and executed recursively. | | + | | ''!&'' | Any | Quoted, space-delimited list of paths to files (see ''!'' for path format explanation). Command with the pattern will be executed only once for all selected files. Cannot be combined with pattern ''!'' and executed recursively. | |
| - | | ''!?prompt[\]?default!'' | Any | When used, user is prompted to enter value that replaces the pattern. ''prompt'' can define a message of the prompt and ''default'' a default value, both can be empty. Special characters entered by user are automatically delimited. You can prohibit this using optional backslash (''\'') before second question mark (''?''). | | + | | ''!/'' | Any | Current remote path. The path always ends with slash. | |
| - | | ''%%!^!%%'' | Local | Name of local file. In general it should be used in combination with ''!'' or ''!&''. Command with the pattern will be executed once for every selected local file, unless only one local file and several remote files are selected and pattern ''!'' is used. Cannot be executed recursively. | | + | | ''!S'' | Any | Current [[session_url|session URL]]. | |
| + | | ''!E'' | Any | Current [[session_url|session URL]] with all [[session_url#advanced|advanced settings]]. You can use it to pass the current session data to another instance of WinSCP (using [[commandline|command-line]] or scripting command ''[[scriptcommand_open|open]]''), or code using WinSCP .NET assembly (see ''[[library_sessionoptions_parseurl|SessionOptions.ParseUrl]]''). Password is included if [[security_credentials|stored or remembered]] only. | | ||
| + | | ''!@'' | Any | Current session hostname. | | ||
| + | | ''!U'' | Any | Current session username. | | ||
| + | | ''!P'' | Any | Current session password (if [[security_credentials|stored or remembered]]). | | ||
| + | | ''!#'' | Any | Current session port number. | | ||
| + | | ''!K'' | Any | Current session private key. | | ||
| + | | ''!N'' | Any | Current session name. | | ||
| + | | ''!?prompt[\]?default!'' | Any | When used, user is prompted to enter value that replaces the pattern. ''prompt'' can define a message of the prompt and ''default'' a default value, both can be empty. Special characters entered by user are automatically delimited. You can prohibit this using optional backslash (''\'') before second question mark (''?''). \\ When implementing an [[extension]], use a runtime [[extension#options|option]] instead, as a more flexible alternative. | | ||
| + | | ''!`==command==`'' | Any | Replaced with output of a given local console command. \\ The command can also be used solely for its side effect, without actually outputting anything. \\ Limited set of static patterns can be used in ''command''. Particularly file patterns, like ''!'' and ''!&'', cannot be used. | | ||
| + | | ''%%!^!%%'' | Local | Full path to a local file. In general it should be used in a combination with ''!'' or ''!&''. Command with the pattern will be executed once for every selected local file, unless only one local file and several remote files are selected and pattern ''!'' is used. Cannot be executed recursively. | | ||
| + | | ''!\'' | Local | Current local path. The path never ends with backslash. | | ||
| The custom command is executed for files selected in [[ui_file_panel|file panel]]. It can be optionally executed also for selected directories or for files in selected directories (or both). | The custom command is executed for files selected in [[ui_file_panel|file panel]]. It can be optionally executed also for selected directories or for files in selected directories (or both). | ||
| ===== [[executing_and_configuring]] Executing and Configuring Custom Commands ===== | ===== [[executing_and_configuring]] Executing and Configuring Custom Commands ===== | ||
| - | Custom commands are located in menu //File(s) > Custom Commands//, in file [[ui_context_menu|context menu]] and on special //[[ui_toolbars#custom_command|Custom Command toolbar]]//. Custom commands can be configured in [[ui_pref_commands|Preferences]]. | + | Custom commands that operate with files are located in menu //Files > File Custom Commands//, in file [[ui_context_menu|context menu]] and on special //[[ui_toolbars#custom_command|Custom Command toolbar]]//. |
| - | You may eventually want to execute ad hoc custom command, without predefining it first. To do so, go to //File(s) > Custom Commands > Enter//. To repeat the last ad hoc custom command, go to //File(s) > Custom Commands > Last//. | + | Custom commands that do not operate with files are located in menu //Commands > Static Custom Commands//, and on special //[[ui_toolbars#custom_command|Custom Command toolbar]]//. |
| + | |||
| + | Custom commands can be configured in [[ui_pref_commands|Preferences]]. | ||
| + | |||
| + | You may eventually want to execute ad hoc custom command, without predefining it first. To do so, go to //Files > Custom Commands > Enter//. To repeat the last ad hoc custom command, go to //Files > Custom Commands > Last//. | ||
| + | |||
| + | Custom commands that are executed [[#types|both with local and remote files]] can be used on [[ui_synchronize_checklist|synchronization checklist window]]. | ||
| + | |||
| + | ===== [[debugging]] Debugging Custom Commands ===== | ||
| + | If you want to test how the patterns in the custom command are expanded, hold down ''Shift'' and ''Ctrl'' keys, while executing the custom command. The command, with all patterns replaced, will get copied to the clipboard, instead of getting executed. | ||
| ===== Useful Custom Commands ===== | ===== Useful Custom Commands ===== | ||
| You can see list of [[custom commands]] other users found useful. | You can see list of [[custom commands]] other users found useful. | ||
| + | |||
| + | ===== Distributing Custom Commands as Extensions ===== | ||
| + | A custom command can be distributed and installed in a form of a [[extension|WinSCP extension file]]. | ||
| + | |||