envTrack

envTrack is a powerful Visual Studio Code extension that enhances your development workflow by providing advanced command execution, configuration management, and YAML file handling capabilities.

Complete documentation can be found here.

Features

Informational Commands

• Live Updates: Commands marked as informational can watch specific files and auto-update their output
• File Watching: Configure file patterns to trigger automatic command execution
• Dynamic Updates: Information displayed updates automatically when watched files change

Command Management

• Run Command: Execute custom commands with flexible argument handling.
• Stop Command: Halt the execution of running commands.
• Add to Favorite: Easily mark commands as favorites for quick access.
• Remove from Favorite: Manage your list of favorite commands.
• Toggle Favorites On/Off: Quickly switch between viewing all commands or only favorites.
• View Command Logs: Access execution logs directly from the running commands tree.

Configuration and Settings

• Open Settings: Directly access and edit the extension's configuration file.
• Copy Configuration Path: Quickly copy configuration paths to the clipboard.
• Refresh Tree: Update the command tree and configuration explorer.
• Setup Configuration: Easily set up EnvTrack by creating a default configuration or linking to an existing one.

Command Colors

Commands can be visually distinguished using color configurations. Available colors for command definitions:

• red - Uses error foreground color
• green - Uses testing passed icon color
• blue - Uses debug start foreground color
• yellow - Uses warning foreground color
• orange - Uses warning notification icon color
• purple - Uses text link foreground color
• gray - Uses description foreground color

Example usage in command configuration:

MyCommand:
  command: "echo Hello"
  color: "green"

Parameter Options

Commands can define parameter options to provide type safety, descriptions, and default values. The structure for parameter options is:

MyCommand:
  command: "echo ${message}"
  paramOptions:
    message:
      type: "string"      # Supported types: string, number, boolean, enum
      description: "The message to echo"
      required: true      # Makes parameter mandatory
    level:
      type: "enum"
      enumValues: ["info", "warn", "error"]
      default: "info"     # Default value if not specified

This feature helps validate parameters and provides better documentation for command usage. The parameter options support:

• Type checking with string, number, boolean, and enum types
• Optional descriptions for better documentation
• Enum values for restricted choices
• Default values
• Required flag for mandatory parameters

View Modes and Navigation

• Toggle View Mode: Switch between 'normal' and 'session' view modes for the command tree.
• Focus Execution: Navigate to specific execution items in the tree view.
• Peek Preview: Get a quick preview of custom commands and their associated kill commands.

YAML File Handling

• Open All YAML Files: Simultaneously open multiple YAML files in separate editor tabs.
• View YAML Files: Quickly access and open YAML files from a list.

Background Processes

• Toggle Background Process: Start or stop background processes associated with internal commands.

Usage

1. Access commands through the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
2. Use the Command Runner view in the VS Code explorer to execute predefined commands.
3. Manage your favorite commands for quick access.
4. Utilize the Configs view to manage and view your command configurations.
5. Take advantage of YAML file management features for easy configuration.
6. If EnvTrack is not set up, use the "EnvTrack: Setup Configuration" command to quickly create or link a configuration.

Requirements

• Visual Studio Code version 1.94.0 or higher

Extension Settings

This extension contributes the following settings:

• env-track.runCommand: Run a JSON Command
• env-track.refreshTree: Refresh the configuration tree
• env-track.showOnlyFavorites: Toggle display of favorite commands only
• env-track.logFolder: Specify custom folder path for command execution logs (defaults to .vscode/logs)
• env-track.hideInformalCommands: Hide informal commands from the command palette when set to true

Shell Options

EnvTrack supports multiple shell environments for command execution:

1. VS Code Integrated Terminal: Default shell integration within VS Code
2. External Terminal: Opens commands in your system's default terminal
3. Custom External Shell: Use a specific terminal by setting externalShellLocation

You can configure your preferred shell environment in the command settings:

commands:
  MyCommand:
    shell: "vscode"    # Uses VS Code integrated terminal
    shell: "external"  # Uses system default or custom external terminal
    externalShellLocation: Terminal

When using external shells, you can specify a custom terminal location through the externalShellLocation setting.

Installation

1. Open Visual Studio Code
2. Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for "envTrack"
4. Click Install

Path Handling

EnvTrack uses both absolute and relative paths in its configuration. Here's a breakdown of path types used in the system:

Paths aliases

Paths aliases can be relative paths and they will resolve for:

• externalConfigPath[i]
• commandTemplatesPaths[i]
• commandFolderPaths[i]
• configs[name].location

Relative Paths

• location (CommandConfig_Config)
• configFile (CommandConfigVSCode)
• externalConfigPath (CommandConfigInternal)
• commandTemplatesPaths (CommandConfigInternal)
• commandFolderPaths (CommandConfigInternal)
• paths (CommandConfigInternal)

Absolute Paths

• rootPath (CommandConfig): Absolute path to the config file's root directory
• projectRootPath (CommandConfig): Absolute path to the project or workspace
• configPath (CommandConfig): Absolute path to the configuration file
• externalConfigPath (CommandConfig): Absolute path to the external configuration file
• originalFilepath (InternalCommand): Absolute path to the original command file
• originalTemplateFilepath (InternalCommand): Absolute path to the original template file

Understanding these path types is crucial for proper configuration and usage of EnvTrack.

All relative paths can be absolute.

Subgroup Commands

EnvTrack now supports subgroup commands, allowing you to define a hierarchy of commands to be executed in a specific order. This feature enhances command organization and execution flexibility.

Subgroup Command Structure

Subgroup commands are defined in YAML files and follow this structure:

Subcommand Command:
  command: <main command>
  params:
    <parameter key>: <parameter value>
  configMap:
    <config key>: <config value>
  subCommands:
    - commandName: <subcommand name>
      params:
        <parameter key>: <parameter value>
      configMap:
        <config key>: <config value>

Execution Order and Parameter Inheritance

1. Subcommands are executed before the main command defined in the root of the subcommand.
2. Parameters and configurations are inherited and overwritten in the following order:
   • Original command definition
   • Subcommand definition
   • Individual subcommand entry definition

This inheritance allows for flexible parameter and configuration management across the command hierarchy.

Example

Here's an example of a subgroup command structure:

Subcommand Command:
  command: echo "Started group"
  params:
    a: b
  configMap:
    cnf: cool
  subCommands:
    - commandName: Test:Echo config map
    - commandName: Test:Echo var
      params:
        echo: bar
    - commandName: Inherit:1
      session:
      params:
      configMap:

In this example, the subcommands will be executed first, followed by the main "Started group" echo command. Parameters and configurations will be inherited and overwritten as specified in the hierarchy.

This powerful feature allows for more complex and organized command structures, enhancing your development workflow with EnvTrack.

Feedback and Contributions

We welcome your feedback and contributions! Please visit our GitHub repository to submit issues, feature requests, or pull requests.

License

MIT License

Enjoy using envTrack to streamline your development workflow!