Run On Save for VS Code

The match and notMatch options use Regular Expressions against the absolute file path.

• Avoid ^: Since the pattern matches against the absolute path, starting with ^ will likely fail unless you provide the full absolute path. Use "match": "somefile\.txt$" instead of "match": "^somefile\.txt$".
• JSON Escaping: Because settings are in JSON, backslashes must be double-escaped. On Windows, a path like C:\folder requires "some\\folder\\.*" in your config.

To use the extension, add the emeraldwalk.runonsave configuration object to your VS Code user or workspace settings. Commands are triggered when saving an existing file. Note that creating new files or using 'Save as...' does not trigger commands.

{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": ".*",
        "cmd": "echo 'Hello World'"
      }
    ]
  }
}

These options are applied to the top-level emeraldwalk.runonsave configuration object.

• shell (optional): Shell path to be used with child_process.exec.
• autoClearConsole (optional): Clears the VSCode output console before commands run. Defaults to false.
• ignoreUnchangedFiles (optional): Ignores files that haven't changed since the last save. Defaults to false.
• message: Message to output before all commands start.
• messageAfter: Message to output after all commands finish.
• showElapsed: If true, shows total elapsed time after all commands finish.

Each object in the commands array defines a specific task to run.

• match: A RegEx pattern for matching files to run this command on.
• notMatch: A RegEx pattern for files to NOT run. This takes precedence over match.
• cmd: The command to execute. Supports placeholder tokens.
• isAsync (optional): If true, the next command in the array will start before this one finishes. Defaults to false.
• message: Message to output before this specific command. Supports placeholders.
• messageAfter: Message to output after this specific command finishes. Supports placeholders.
• showElapsed: If true, shows elapsed time for this specific command.
• autoShowOutputPanel: Controls output panel visibility:
  • never: Default behavior.
  • always: Shows the panel when the first command starts.
  • error: Shows the panel only when a command fails.

The IConfig interface defines the top-level configuration for the extension. You can configure the shell used for execution, whether to clear the console automatically, and whether to ignore files that haven't changed. The core functionality is driven by the commands array.

{
  "shell": "/bin/bash",
  "autoClearConsole": true,
  "ignoreUnchangedFiles": false,
  "showElapsed": true,
  "commands": [
    {
      "cmd": "echo 'hello'",
      "match": "\\.txt$",
      "isAsync": false
    }
  ]
}

Each command in the commands array is defined by the ICommand interface. You can specify which files to trigger the command using match (regex) or notMatch (regex exclusion), the command string itself (cmd), and whether it should run asynchronously (isAsync). You can also control how the output panel is displayed using autoShowOutputPanel.

{
  "cmd": "npm test",
  "match": "\\.ts$",
  "notMatch": "\\.spec\.ts$",
  "isAsync": true,
  "autoShowOutputPanel": "error",
  "message": "Running tests...",
  "messageAfter": "Tests finished.",
  "showElapsed": true
}

Both the global configuration and individual commands support messaging options via IMessageConfig. This allows you to provide feedback in the VS Code UI when commands run.

• message: A string to display when a command starts.
• messageAfter: A string to display after a command completes.
• showElapsed: A boolean indicating whether to show the time taken for execution.
• autoShowOutputPanel: (Command-specific) Controls the visibility of the output panel. Options are 'always', 'error', or 'never'.

Commands and messages support placeholders for file and environment information.

File Tokens:

• ${workspaceFolder}: Path of the workspace folder of the saved file.
• ${file}: Full path of the saved file.
• ${fileBasename}: Filename including extension.
• ${fileDirname}: Directory name of the saved file.
• ${fileExtname}: File extension (including the dot).
• ${fileBasenameNoExt}: Filename without the extension.
• ${relativeFile}: Path of the file relative to ${workspaceFolder}.
• ${cwd}: The current working directory VS Code is running in (not the project directory).

Environment Tokens:

• ${env.Name}: Access environment variables (e.g., ${env.USERNAME}).

You can control the extension's execution state using the following commands in the VS Code Command Palette:

• On Save: Enable
• On Save: Disable
• On Save: Toggle

You can manually control whether the extension is active using the following VS Code commands. These commands toggle the isEnabled state of the extension, allowing you to pause or resume automatic command execution without changing your global configuration.

extension.emeraldwalk.enableRunOnSave
extension.emeraldwalk.disableRunOnSave
extension.emeraldwalk.toggleRunOnSave