Source Control Overview
Purpose and Scope
Visual Studio Code's integrated source control management, usually shortened to SCM, gives users a common editor surface for Git and other version control systems. The user problem is straightforward: developers need to review file changes, stage or unstage work, write commit messages, switch branches, and resolve collaboration issues without losing the context of their editor. The Source Control view is the shared workbench surface for those activities, while the underlying provider can be Git, another installed extension, or a custom SCM provider built on the extension API.
The official product documentation describes Git support as built in and emphasizes that the UI works alongside command-line Git rather than replacing it. That distinction matters for contributors and extension authors: VS Code is not a separate version-control database, and the SCM view is not Git-only. It is a common model that providers populate with resource states, groups, commands, and menus. The repository evidence on this page focuses on proposed menu contribution points that let extensions add commands into specific SCM UI locations. Sources: src/vscode-dts/vscode.proposed.contribSourceControlArtifactGroupMenu.d.ts, src/vscode-dts/vscode.proposed.contribSourceControlArtifactMenu.d.ts
Relevant Source Files
src/vscode-dts/vscode.proposed.contribSourceControlArtifactGroupMenu.d.ts— declares the proposed placeholder for thescm/artifactGroup/contextmenu contribution point, used to target context actions at a group of SCM artifacts.src/vscode-dts/vscode.proposed.contribSourceControlArtifactMenu.d.ts— declares the proposed placeholder for thescm/artifact/contextmenu contribution point, used to target context actions at an individual SCM artifact.src/vscode-dts/vscode.proposed.contribSourceControlHistoryItemMenu.d.ts— declares the proposed placeholder for thescm/historyItem/contextmenu contribution point, used to target actions at a single history item.src/vscode-dts/vscode.proposed.contribSourceControlHistoryTitleMenu.d.ts— declares the proposed placeholder for thescm/history/titlemenu contribution point, used to target commands in the source-control history title area.src/vscode-dts/vscode.proposed.contribSourceControlInputBoxMenu.d.ts— declares the proposed placeholder for thescm/inputBoxmenu contribution point, used to target commands near the SCM input box where commit-message and provider-specific text entry happens.src/vscode-dts/vscode.proposed.contribSourceControlTitleMenu.d.ts— declares the proposed placeholder for thescm/sourceControl/titlemenu contribution point, used to target commands in a source-control provider title area.
These files are deliberately small, but they are important because VS Code's extension API surface is partly represented by declaration files under src/vscode-dts. In this set, each file is an empty placeholder declaration for a named menu contribution point. An empty placeholder still has architectural meaning: it records that the menu location exists as a proposed contribution surface and gives extension manifests a stable identifier to target while the proposal is tracked through its linked issue. Sources: src/vscode-dts/vscode.proposed.contribSourceControlHistoryItemMenu.d.ts, src/vscode-dts/vscode.proposed.contribSourceControlHistoryTitleMenu.d.ts
Core SCM Concepts
The SCM model is provider-oriented. A provider creates a SourceControl object, organizes files or other changed resources into SourceControlResourceGroup instances, and represents each changed item as a SourceControlResourceState. In Git terms, staged changes and unstaged changes are natural resource groups, while modified, deleted, renamed, or newly added files are resource states. The user sees these abstractions as a tree or list of changes in the Source Control view, but the extension API keeps the provider responsible for deciding what the resources mean and which commands apply.
The input box is another core concept because committing is usually text-driven. For Git, it is where the commit message is written before invoking a commit command. For another SCM provider, the same space might collect a changelist description, a review message, or a provider-specific operation summary. The proposed scm/inputBox menu contribution point exists because commands near that box need a different context from file commands. A command that inserts a template, validates a message, or opens provider-specific help belongs beside the text-entry workflow, not beside an individual changed file. Sources: src/vscode-dts/vscode.proposed.contribSourceControlInputBoxMenu.d.ts
History is a separate but related surface. Day-to-day SCM work starts with the working tree, but developers also need to inspect previous changes, compare versions, understand when a line of development changed, and act on historical records. The proposed history title and history item menu locations split those needs into two scopes. A title command can refresh, filter, or change how history is displayed, while an item command can open, compare, copy, cherry-pick, or otherwise act on a specific record, depending on what the provider implements. Sources: src/vscode-dts/vscode.proposed.contribSourceControlHistoryTitleMenu.d.ts, src/vscode-dts/vscode.proposed.contribSourceControlHistoryItemMenu.d.ts
System-to-Code Mapping
The requested source files map to the extension contribution layer rather than to the Git implementation itself. Their names follow the vscode.proposed.*.d.ts convention, which means they describe proposed API or contribution metadata available to extension authors who opt into the matching proposal. The comments identify menu contribution point IDs such as scm/sourceControl/title, scm/artifact/context, and scm/historyItem/context. Those IDs are the bridge between a user-visible place in the SCM UI and the command declarations that an extension contributes through its manifest.
| SCM surface | Contribution point | Repository declaration | Typical command scope |
|---|---|---|---|
| Source control provider title | scm/sourceControl/title | src/vscode-dts/vscode.proposed.contribSourceControlTitleMenu.d.ts | Provider-level commands such as sync, refresh, publish, or provider settings |
| SCM input box | scm/inputBox | src/vscode-dts/vscode.proposed.contribSourceControlInputBoxMenu.d.ts | Commit-message or text-entry commands |
| Artifact group | scm/artifactGroup/context | src/vscode-dts/vscode.proposed.contribSourceControlArtifactGroupMenu.d.ts | Commands that apply to a collection of related artifacts |
| Artifact | scm/artifact/context | src/vscode-dts/vscode.proposed.contribSourceControlArtifactMenu.d.ts | Commands that apply to one artifact or changed item |
| History title | scm/history/title | src/vscode-dts/vscode.proposed.contribSourceControlHistoryTitleMenu.d.ts | History-view commands such as filtering or refresh |
| History item | scm/historyItem/context | src/vscode-dts/vscode.proposed.contribSourceControlHistoryItemMenu.d.ts | Commands that act on a single history entry |
A useful way to read this mapping is by scope. Title menus are broad: they attach to the provider or history view as a whole. Context menus are narrow: they attach to a selected artifact, group, or history item. The input-box menu is workflow-specific: it supports the commit or message-entry moment. Separating these contribution points prevents a provider from overloading one generic menu with commands that only make sense in some contexts, and it lets VS Code present commands where users are already looking. Sources: src/vscode-dts/vscode.proposed.contribSourceControlTitleMenu.d.ts, src/vscode-dts/vscode.proposed.contribSourceControlArtifactMenu.d.ts
Execution Flow for Users and Providers
For users, the normal flow begins when a folder is opened. If the folder is a Git repository and Git is installed, the built-in Git provider activates and populates the Source Control view. The user can review changed files, stage selected resources, enter a commit message, commit, synchronize with a remote, and continue using the terminal for any command-line operation they prefer. Because VS Code reflects the repository state, command-line Git operations and UI operations remain part of the same workflow rather than separate histories.
For providers, the flow is inverted. The provider first creates and updates the SCM model, then contributes commands that make sense for each visible state. File-level actions should be exposed against resource states or artifacts, group-level actions against groups, and provider-wide actions against the title area. The proposed declaration placeholders in this page show that VS Code is refining that command-placement vocabulary for newer SCM surfaces such as artifacts and history. Extension authors should treat these menu IDs as precise UI contracts instead of using a broader menu simply because it is available.
A provider also needs to think about disabled, unavailable, and empty states. If there are no changes, the Source Control view should not feel broken; it should guide the user toward initialization, cloning, publishing, or refreshing, depending on the provider. If the user has no configured identity, a commit command may need to explain what is missing. If a history entry cannot be acted on, the context menu should avoid presenting commands that will fail. The menu contribution points do not implement those policies by themselves, but they define where policy-aware commands can appear. Sources: src/vscode-dts/vscode.proposed.contribSourceControlArtifactGroupMenu.d.ts, src/vscode-dts/vscode.proposed.contribSourceControlInputBoxMenu.d.ts
Extension and API Components
The public SCM extension story has two layers. The model layer is the Source Control API, where providers publish resources, groups, decorations, and commands. The contribution layer is the manifest-driven command placement system, where providers attach commands to menus. The files listed here belong to the second layer. They do not define SourceControl or resource-state types; instead, they reserve named SCM menu locations so that extension manifests and proposed API consumers can target the correct part of the workbench UI.
The distinction is important when designing an extension. If the provider cannot accurately model changed resources, better menus will not fix the experience. Conversely, if the model is accurate but commands are attached to the wrong surface, users will struggle to discover safe actions. A revert command belongs on an artifact or resource item, not necessarily in the provider title. A commit-template command belongs by the input box, not on every changed file. A history comparison command belongs on a history item, while a history refresh command belongs in the history title.
Because these are proposed declaration files, extension authors should expect the usual proposed-API discipline: opt in intentionally, track the linked proposal issue, and be ready for naming or behavior changes before stabilization. The repository comments include issue references for each placeholder, which is the normal path for discussion and iteration. Stable extensions should prefer finalized API and menu contribution points when possible, while experimental or first-party extensions can use proposed points to validate new SCM workflows before they become permanent. Sources: src/vscode-dts/vscode.proposed.contribSourceControlHistoryItemMenu.d.ts, src/vscode-dts/vscode.proposed.contribSourceControlHistoryTitleMenu.d.ts, src/vscode-dts/vscode.proposed.contribSourceControlTitleMenu.d.ts
Testing Signals and Next Steps
For repository contributors, these declarations are type-surface signals. A change to a proposed menu identifier can affect extension manifests, documentation, and any tests that exercise command visibility in the SCM view. The safest validation strategy is to test at three levels: declaration compilation for the proposed vscode-dts surface, extension-manifest contribution behavior for each menu ID, and workbench UI behavior for command placement. Even when the declaration file is only a placeholder, the string identifier is externally meaningful to proposed consumers.
For extension authors, the next step is to start from the official Source Control API guide and implement the SCM model before adding advanced menu placement. Create a provider, populate groups and resource states, verify that the Source Control view reflects repository changes, then add commands to the narrowest menu that matches the user action. Use scm/sourceControl/title for provider-wide actions, scm/inputBox for message-entry helpers, artifact menus for changed-item operations, and history menus for historical records. That sequencing keeps the extension understandable and makes the UI feel native rather than bolted on.
Related pages in this wiki continue the source-control journey from different angles. Read git-extension-api for extension-facing Git APIs, github-authentication-and-pull-requests for GitHub collaboration workflows, and merge-conflict-resolution for conflict-focused behavior. If your task is user education, begin with the official Source Control overview concepts: install Git, open or initialize a repository, review changes in the Source Control view, commit with a configured identity, and use the command line whenever it is the clearer tool. If your task is contribution work, treat the menu IDs on this page as source-backed integration points that need careful compatibility review.