History Tracking System
Relevant source files
The following files were used as context for generating this wiki page:
The History Tracking System in vscli is a core module responsible for persisting and managing a record of recently opened Visual Studio Code workspaces and dev containers. Its primary purpose is to enable users to quickly reopen previous projects with their associated configurations (editor commands, launch behaviors, and arguments) through both the command-line interface and an interactive Terminal User Interface (TUI).
The system maintains a local JSON database of workspace metadata, ensuring that frequent project environments are easily accessible. It handles the lifecycle of history entries, including creation during an "open" command, retrieval for the "recent" TUI, and automated cleanup to keep the history file size manageable.
Core Data Structures
The system is built around three primary entities: the Entry, the History container, and the Tracker manager.
Entry
A single record in the history representing a workspace. It stores the workspace name, the path to the project, dev container specific metadata, and the exact behavior used to launch the editor.
Sources: src/history.rs:18-31
History
A wrapper around a HashMap<EntryId, Entry> that provides methods for CRUD operations. While it uses a HashMap for efficient lookups by ID, it implements custom logic for "upserting" entries to prevent duplicates based on path and behavior.
Sources: src/history.rs:71-72, src/history.rs:103-115
Tracker
The high-level manager responsible for file I/O. It handles loading the history from the local data directory and storing it back to disk while enforcing a maximum entry limit.
Sources: src/history.rs:131-136
| Field | Type | Description |
|---|---|---|
workspace_name | String | The display name of the workspace folder. |
dev_container_name | Option<String> | The name of the dev container config, if applicable. |
workspace_path | PathBuf | Canonicalized filesystem path to the project. |
config_path | Option<PathBuf> | Path to the specific .devcontainer.json used. |
behavior | Behavior | Struct containing the editor command, strategy, and arguments. |
last_opened | DateTime<Utc> | Timestamp of the last access. |
Sources: src/history.rs:20-30
Architecture and Data Flow
The History Tracking System interacts with the CLI entry point and the UI module to synchronize state.
The diagram shows how the Tracker acts as the bridge between the running application and the physical storage on disk.
Sources: src/history.rs:16, src/main.rs:49-61
Persistence Logic
The Tracker manages the history.json file, typically located in the user's local data directory (e.g., ~/.local/share/vscli/history.json).
- Loading: During initialization, the system attempts to read the JSON file into a
Vec<Entry>. If parsing fails, it renames the broken file to a.bakextension and starts with a fresh history to prevent application crashes. - Saving: When the application exits, the
Tracker::storemethod is called. It sorts the entries and truncates the list to theMAX_HISTORY_ENTRIES(currently 35) before writing to disk.
Sources: src/history.rs:141-150, src/history.rs:166-180, src/history.rs:204-213
Integration with TUI
The history system provides the data source for the recent command's interactive UI. The ui.rs module converts history entries into TableRow structures for display in a ratatui table.
The sequence demonstrates how the UI interacts directly with the Tracker's history state during a session.
Sources: src/ui.rs:271-285, src/main.rs:90-95
Filtering and Selection
The UI implements a fuzzy search mechanism using nucleo-matcher. When a user types in the search box, the TableData struct applies a filter across the workspace name, container name, and path. The history system's EntryId ensures that even as the displayed list is reordered or filtered, the correct underlying data is referenced.
Sources: src/ui.rs:136-155, src/ui.rs:188-217
Launch Behavior Tracking
A critical component of the history is the Behavior struct. This ensures that if a user opens a project with a specific editor (like cursor) or specific flags (like --disable-gpu), these preferences are remembered.
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct Behavior {
pub strategy: ContainerStrategy,
pub args: Vec<OsString>,
#[serde(default = "default_editor_command")]
pub command: String,
}
Sources: src/launch.rs:65-71
When reopening via the recent command, the CLI allows these stored behaviors to be overridden by new command-line flags before the launch occurs.
Sources: src/main.rs:100-118
Summary
The History Tracking System provides the "memory" for vscli. By encapsulating the complexity of file management, duplicate detection (via path-based equality), and size limiting, it allows the rest of the application to treat recent projects as a reliable, queryable stream of data. Its integration with the TUI provides a seamless "recents" experience while maintaining technical metadata necessary for complex dev container launches.