Troubleshooting & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The vscli tool implements a robust diagnostic system centered around tiered logging, error reporting, and dry-run execution modes. This system allows developers and users to inspect the internal state of the application, verify command-line arguments, and validate dev container detection logic without executing external editor commands.
The primary components of this system include env_logger for terminal output, color-eyre for rich error reports, and a custom log formatter designed to maintain a minimalistic UI while providing deep technical insights during debugging.
Logging System Architecture
Logging in vscli is initialized at the entry point of the application. It utilizes the log crate as an abstraction layer and env_logger as the implementation. The verbosity is controlled by user-provided flags which map to standard log levels.
Log Initialization and Formatting
The application uses a custom formatter to balance user-friendly output with technical detail. If the log level is set to Info, the output is clean and lacks prefixes. For all other levels (Trace, Debug, Warn, Error), the output is prefixed with a color-coded single-letter indicator.
Sources: src/main.rs:36-44, src/main.rs:135-168
Log Levels and Verbosity
The verbosity is managed via the clap-verbosity-flag crate, allowing users to increase or decrease logging output through CLI flags.
| Log Level | Prefix | Color | Usage in Code |
|---|---|---|---|
Trace | T | White | Detailed internal state (e.g., full parsed options, path canonicalization). |
Debug | D | Cyan | Component-level events (e.g., terminal mode changes, UI start, command execution). |
Info | I | Green | General user feedback (e.g., "Opening dev container..."). |
Warn | W | Yellow | Recoverable issues (e.g., history file corruption, backup creation). |
Error | E | Red | Critical failures (e.g., missing editor executables, invalid paths). |
Sources: src/main.rs:143-167, src/opts.rs:30-31, src/history.rs:163-176
Troubleshooting Modes
Dry Run Execution
The --dry-run (or -d) flag is a critical troubleshooting tool. When enabled, it prevents the final execution of the editor command while still performing all detection, configuration parsing, and URI generation steps. This allows users to verify what vscli would do without actually launching an editor.
Error Reporting with color-eyre
The application uses color-eyre for idiomatic error handling. This provides panic hooks and rich backtraces. Most functions return a Result<T> and use .wrap_err() or .wrap_err_with() to provide context to failures, such as which file failed to parse or which command was missing.
Sources: src/main.rs:34, src/workspace.rs:108-111, src/workspace.rs:218-219
History and State Debugging
vscli tracks workspace history in a JSON file. Troubleshooting issues related to "Recent" projects often involves inspecting this file or its automated recovery process.
History Recovery Logic
If the history file becomes corrupted (e.g., invalid JSON), vscli attempts to troubleshoot this automatically by:
- Identifying the broken file.
- Finding a unique backup name (e.g.,
.history_0.json.bak). - Renaming the broken file and starting a fresh history.
- Logging a warning to the user about the relocation of the broken file.
Sources: src/history.rs:142-178
UI State and Selection
When using the TUI (vscli recent), the application logs UI transitions and terminal state changes to help debug layout or input issues.
| Component | Debug Action | File Reference |
|---|---|---|
| Terminal | Logs "Entering raw mode" and "Terminal restored" | src/ui.rs:228-251 |
| Search | Logs filter application and search score changes | src/ui.rs:125-149 |
| Workspace | Logs variable substitution results in devcontainer.json | src/workspace.rs:59-71 |
Summary
Troubleshooting in vscli is facilitated by a multi-layered approach: Trace logs provide visibility into path manipulation and URI generation, the Dry Run mode allows for safe verification of the launch logic, and the custom log_format ensures that diagnostic information is available without cluttering the standard user interface. Error context wrapping ensures that when failures occur, the user is provided with specific file paths and operation descriptions to assist in resolution.