Git Extension API

The bundled Git extensions expose typed APIs for extension authors who want to integrate with VS Code's source-control experience instead of reimplementing repository discovery, remote selection, or Git metadata handling. This page explains the two public contracts represented in this repository: vscode.git, which exposes repository-oriented Git data and operations through git.d.ts, and vscode.git-base, which exposes static Git contributions and the remote repository picker through git-base.d.ts. The APIs are consumed by other extensions through VS Code's extension host, so callers should treat them as extension-to-extension contracts rather than Node packages imported from the repository at runtime.

Sources: extensions/git/README.md, extensions/git/src/api/git.d.ts, extensions/git-base/README.md, extensions/git-base/src/api/git-base.d.ts

Purpose and Scope

Use the Git API when an extension needs to understand local repository state, inspect branches, refs, remotes, worktrees, submodules, changes, or Git log metadata in a way that matches VS Code's built-in Git extension. The Git README states that this extension is bundled with Visual Studio Code, can be disabled, and exposes an API reachable by any other extension. That matters for extension authors because the user does not install a separate npm dependency for Git integration; instead, the extension copies the declaration file for compilation and obtains the runtime object from the activated vscode.git extension.

Sources: extensions/git/README.md, extensions/git/src/api/git.d.ts

Use the Git Base API when an extension contributes or consumes remote repository sources. The Git Base README describes the extension as bundled and focused on static Git contributions and a remote repository picker. Its declaration file centers on RemoteSourceProvider, remote source objects, recent sources, picker options, and remote-source actions. In practice, this is the API to use when an extension wants to make a host such as a repository service appear in VS Code's clone/open flow, or when it wants to ask the user to select a remote URL and optionally a branch.

Sources: extensions/git-base/README.md, extensions/git-base/src/api/git-base.d.ts

These APIs sit inside the broader VS Code extension model. Official VS Code documentation emphasizes that extensions plug into the editor through the same extensibility model used by built-in features, and that extensions run with the permissions of VS Code itself. For this page, that means API consumers should design for explicit activation dependencies, user-visible contribution behavior, and enterprise/security review. A remote source provider can influence where users clone code from, and a Git API consumer can observe repository metadata and file-change state, so callers should keep trust, workspace boundaries, and user intent visible in their UI.

Relevant Source Files

• extensions/git/README.md - Documents that the Git extension is bundled with VS Code, can be disabled but not uninstalled, and shows the supported pattern for obtaining vscode.git API version 1 from another extension.
• extensions/git/src/api/git.d.ts - Declares the public TypeScript contract for the Git extension, including refs, branches, commits, remotes, worktrees, change status, repository state, UI state, access details, and log options visible in the supplied source evidence.
• extensions/git-base/README.md - Documents that Git Base is bundled, provides static Git contributions and the remote repository picker, and shows the supported pattern for obtaining vscode.git-base API version 1.
• extensions/git-base/src/api/git-base.d.ts - Declares the public remote-source API, including API, GitBaseExtension, PickRemoteSourceOptions, PickRemoteSourceResult, RemoteSourceProvider, RemoteSource, RecentRemoteSource, and RemoteSourceAction.

Activation and Consumption Flow

Both README files describe a copy-and-consume pattern. The declaration file is copied into the consuming extension's sources, included in that extension's TypeScript compilation, and used only for typing the API returned by vscode.extensions.getExtension(...).exports. For the Git extension, the README also calls out an important activation detail: add vscode.git to extensionDependencies so VS Code activates the Git extension before the consumer asks for its exports. Without that dependency, a consumer may reach for an export before the providing extension is ready.

Sources: extensions/git/README.md, extensions/git-base/README.md

const gitExtension = vscode.extensions.getExtension<GitExtension>('vscode.git').exports;
const git = gitExtension.getAPI(1);

"extensionDependencies": [
  "vscode.git"
]

The Git Base README shows the same runtime pattern with the vscode.git-base extension identifier and API version 1. The declaration file makes enablement an explicit part of the contract: GitBaseExtension has enabled, onDidChangeEnablement, and getAPI(version: 1). Its comment states that getAPI throws if Git Base is disabled and points consumers to the enablement event to know when the extension becomes enabled or disabled. A robust remote-source integration should therefore subscribe to enablement changes or gracefully defer remote-picker work until the provider is available.

Sources: extensions/git-base/README.md, extensions/git-base/src/api/git-base.d.ts

const gitBaseExtension = vscode.extensions.getExtension<GitBaseExtension>('vscode.git-base').exports;
const gitBase = gitBaseExtension.getAPI(1);

Git API Data Model

The visible git.d.ts API evidence defines a source-control vocabulary that mirrors Git concepts while staying usable from VS Code extensions. Git exposes the executable path, and InputBox exposes a mutable value, giving consumers entry points for Git installation details and commit-message UI state. The enum and interface set then describes repository facts: RefType distinguishes heads, remote heads, and tags; Ref carries an optional name, commit, commit details, and remote; Branch extends Ref with upstream, ahead, and behind counts; and UpstreamRef names the remote tracking branch.

Sources: extensions/git/src/api/git.d.ts

Commit and topology data are represented with small, typed records. Commit includes a hash, message, parent hashes, optional author and committer dates, optional author identity, and optional CommitShortStat. CommitShortStat reports files, insertions, and deletions, which is useful for history UI, review summaries, or analytics surfaces that do not need a full diff. The API also models Submodule, Remote, and Worktree, allowing consumers to reason about nested repositories, fetch and push URLs, read-only remotes, named worktrees, detached worktrees, and which worktree is the main one.

Sources: extensions/git/src/api/git.d.ts

Change state is represented by the Status enum and Change interfaces. The enum covers index states such as modified, added, deleted, renamed, and copied; working tree states such as modified, deleted, untracked, ignored, intent-to-add, intent-to-rename, and type-changed; and merge-conflict states such as added by us, deleted by them, both added, or both modified. Change exposes uri, originalUri, renameUri, and status, with a comment advising consumers to prefer uri when unsure because it resolves rename cases. DiffChange adds insertion and deletion counts.

Sources: extensions/git/src/api/git.d.ts

RepositoryState is the central visible snapshot of a repository. It exposes HEAD, all refs, remotes, submodules, worktrees, and a possible rebaseCommit. It also groups changes into mergeChanges, indexChanges, workingTreeChanges, and untrackedChanges, and includes onDidChange for state updates. A separate RepositoryUIState tells whether a repository is selected and emits its own change event. These two state objects let a consumer separate source-control facts from workbench selection state, which is important for multi-repository workspaces.

Sources: extensions/git/src/api/git.d.ts

Git Base Remote Source API

The Git Base API interface has three visible methods. registerRemoteSourceProvider(provider: RemoteSourceProvider): Disposable adds a provider and returns a disposable registration. getRemoteSourceActions(url: string): Promise<RemoteSourceAction[]> asks registered providers for actions associated with a remote URL. pickRemoteSource(options: PickRemoteSourceOptions): Promise<string | PickRemoteSourceResult | undefined> opens the remote source picker and returns either a URL string, a structured URL-and-branch result, or undefined when no selection is made. The return type changes with options: the branch option indicates that the result is PickRemoteSourceResult. Sources: extensions/git-base/src/api/git-base.d.ts

RemoteSourceProvider is the provider contract for services that list repositories or recent remotes. It has a required name and optional icon, label, placeholder, and supportsQuery. Provider methods are optional so implementations can expose the capabilities they actually support: getBranches(url), getRemoteSourceActions(url), getRecentRemoteSources(query), and getRemoteSources(query). Each method returns ProviderResult, matching VS Code's convention for APIs that can return a value, promise, null, or undefined depending on provider availability and cancellation patterns.

Sources: extensions/git-base/src/api/git-base.d.ts

Remote items and actions are deliberately UI-oriented. RemoteSource includes name, optional description, optional detail, optional codicon icon, and a url that may be a single string or multiple strings. RecentRemoteSource extends it with a timestamp so the picker can surface recent activity. RemoteSourceAction has a label, codicon icon, and run(branch: string): void, which lets providers attach branch-aware commands to a selected remote. Picker options let the caller customize labels, provider filtering, title, placeholder, branch selection, and whether recent sources should be shown.

Sources: extensions/git-base/src/api/git-base.d.ts

Compact Reference

Implementation Guidance and Next Steps

When building against these APIs, keep the declaration files in your extension source tree and treat version 1 as the explicit compatibility boundary. Prefer narrow integration points: use the Git API to observe repository state and render UI that reacts to onDidChange, and use Git Base when the workflow is specifically about choosing or contributing remote sources. Avoid assuming that a bundled extension is always enabled. The README notice for both extensions says they can be disabled, and the Git Base declaration makes disablement part of the runtime contract.

Sources: extensions/git/README.md, extensions/git-base/README.md, extensions/git-base/src/api/git-base.d.ts

A good next step for a repository-state consumer is to model which RepositoryState arrays matter to the feature: staged changes, working tree changes, untracked changes, merge changes, refs, or remotes. For a remote-provider author, start with RemoteSourceProvider.name, decide whether the provider supports search queries, then implement only the source, recent-source, branch, and action methods that the service can answer reliably. Related pages to read next are Source Control Overview for the user-facing SCM workflow, GitHub Authentication and Pull Requests for collaboration surfaces, and Extension Authoring Overview for the surrounding extension-host model.