History File Format & Customization
Relevant source files
The following files were used as context for generating this wiki page:
The vscli tool maintains a persistent history of recently opened workspaces and their specific launch configurations. This system allows users to quickly reopen projects with preserved settings such as launch strategies, custom editor commands, and additional CLI arguments. The history is primarily managed through the Tracker and History modules, which handle serialization to a JSON format on the local disk.
The history system serves as the data backbone for the Interactive UI (vscli recent), enabling fuzzy searching and selection of previous environments. It supports customization of the storage location via environment variables or CLI flags, and includes built-in recovery mechanisms for corrupted data files.
Sources: src/history.rs, src/main.rs:37-51, README.md:124-140
History Data Structures
The core of the history system is the Entry struct, which encapsulates all metadata required to reconstruct a specific VS Code or Dev Container launch.
The Entry Model
Each record in the history file represents a unique combination of a workspace path, a dev container configuration, and the launch behavior used.
| Field | Type | Description |
|---|---|---|
workspace_name | String | The display name of the workspace. |
dev_container_name | Option<String> | The name defined in the dev container config, if applicable. |
workspace_path | PathBuf | Absolute path to the local project folder. |
config_path | Option<PathBuf> | Path to the specific .devcontainer.json used. |
behavior | Behavior | Struct containing the strategy, command, and extra args. |
last_opened | DateTime<Utc> | Timestamp used for sorting and pruning. |
Sources: src/history.rs:18-30
Launch Behavior Persistence
The Behavior struct, embedded within each history entry, ensures that user-defined customization for a specific project is remembered.
pub struct Behavior {
pub strategy: ContainerStrategy,
pub args: Vec<OsString>,
pub command: String,
}
Sources: src/launch.rs:64-70
History File Management
The Tracker struct manages the lifecycle of the history file, including loading from disk, handling IO errors, and enforcing storage limits.
Default Storage and Overrides
By default, vscli stores the history file in the local data directory of the operating system.
- Default Path:
{local_data_dir}/vscli/history.json - Manual Override: Users can specify a custom path using the
-sor--history-pathflag, or by setting theHISTORY_PATHenvironment variable.
Sources: src/main.rs:40-48, src/opts.rs:21-23
Load and Pruning Logic
When the application starts, it loads the JSON array of entries. To prevent the file from growing indefinitely, the system enforces a maximum limit.
The system maintains a maximum of 35 entries (MAX_HISTORY_ENTRIES). When saving, entries are pruned based on their order in the collection.
Sources: src/history.rs:15, src/history.rs:136-150, src/history.rs:184-191
Data Integrity & Corruption Handling
If the history file becomes unreadable (e.g., due to manual editing or version conflicts), vscli implements an automatic recovery flow. Instead of failing, it renames the broken file to a backup format (.history_{i}.json.bak) and initializes a fresh history file.
Sources: src/history.rs:152-171
Customization via CLI and UI
Users can interact with and customize the history through various commands and UI actions.
History Interactions
The history is updated in two primary scenarios:
- Opening a new path: A new entry is "upserted" (updated if existing, inserted if new).
- Recent UI Selection: When an entry is selected in the UI, its
last_openedtimestamp and any overridden launch arguments are updated.
Sources: src/main.rs:88-115, src/history.rs:114-128
User-Triggered Deletion
Users can manually remove entries from the history file using the Interactive UI. Pressing Delete, Ctrl+R, or Ctrl+X within the TUI triggers a deletion from the History hashmap, which is persisted when the application exits.
Sources: src/ui.rs:293-300, README.md:144
Summary of Configuration Options
| Option | Flag / Environment Var | Purpose |
|---|---|---|
| History Path | --history-path / HISTORY_PATH | Changes where history.json is saved. |
| Dry Run | --dry-run / DRY_RUN | Simulates the launch; history is updated but editor isn't opened. |
| Launch Behavior | --behavior | Sets the strategy (detect, force-container, force-classic) stored in history. |
| Command | --command / COMMAND | Specifies the editor (e.g., cursor, code-insiders) to associate with the entry. |
Sources: src/opts.rs:25-55, README.md:95-122
The vscli history system provides a seamless way to manage development environments by combining persistent storage with an interactive interface, ensuring that complex launch configurations are easily accessible for repeat use.