ソース管理API

ソース管理APIにより、拡張機能の作成者はソース管理 (SCM) 機能を定義できます。スリムながらも強力なAPIは、多くの異なるSCMシステムをVisual Studio Codeに統合しつつ、それらすべてに共通のユーザーインターフェースを提供します。

VS Code SCM

VS Code自体には、Git拡張機能という1つのソース管理プロバイダーが同梱されており、これはこのAPIの最良のリファレンスであり、独自のSCMプロバイダーを開発したい場合の優れた出発点となります。マーケットプレイスには、SVN拡張機能など、他にも良い例があります。

このドキュメントは、あらゆるSCMシステムをVS Codeで動作させる拡張機能を構築するのに役立ちます。

注: ドキュメントのvscode 名前空間APIリファレンスをいつでも参照できます。

ソース管理モデル

SourceControl は、ソース管理モデルにリソース状態 (SourceControlResourceState のインスタンス) を設定する責任を負うエンティティです。リソース状態はそれ自体がグループ (SourceControlResourceGroup のインスタンス) に整理されています。

vscode.scm.createSourceControl を使用して新しい SourceControl を作成できます。

これら3つのエンティティが互いにどのように関連しているかをよりよく理解するために、Git を例にとりましょう。git status の以下の出力を考えてみましょう。

vsce main* → git status
On branch main
Your branch is up-to-date with 'origin/main'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   README.md
        renamed:    src/api.ts -> src/test/api.ts

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        deleted:    .travis.yml
        modified:   README.md

このワークスペースでは多くのことが起きています。まず、README.md ファイルが変更され、ステージングされ、その後再び変更されました。次に、src/api.ts ファイルが src/test/api.ts に移動され、その移動がステージングされました。最後に、.travis.yml ファイルが削除されました。

このワークスペースについて、Gitは2つのリソースグループを定義します。ワーキングツリーとインデックスです。そのグループ内の各ファイル変更はリソース状態です。

インデックス - リソースグループ
- README.md、変更済み - リソース状態
- src/test/api.ts、src/api.ts から名前が変更されました - リソース状態
ワーキングツリー - リソースグループ
- .travis.yml、削除済み - リソース状態
- README.md、変更済み - リソース状態

同じファイル README.md が2つの異なるリソース状態の一部になっている点に注目してください。

Gitがこのモデルを作成する方法は次のとおりです

function createResourceUri(relativePath: string): vscode.Uri {
  const absolutePath = path.join(vscode.workspace.rootPath, relativePath);
  return vscode.Uri.file(absolutePath);
}

const gitSCM = vscode.scm.createSourceControl('git', 'Git');

const index = gitSCM.createResourceGroup('index', 'Index');
index.resourceStates = [
  { resourceUri: createResourceUri('README.md') },
  { resourceUri: createResourceUri('src/test/api.ts') }
];

const workingTree = gitSCM.createResourceGroup('workingTree', 'Changes');
workingTree.resourceStates = [
  { resourceUri: createResourceUri('.travis.yml') },
  { resourceUri: createResourceUri('README.md') }
];

ソース管理およびリソースグループへの変更は、ソース管理ビューに反映されます。

ソース管理ビュー

VS Codeは、ソース管理モデルが変更されると、ソース管理ビューを設定できます。リソース状態は SourceControlResourceDecorations を使用してカスタマイズ可能です。

export interface SourceControlResourceState {
  readonly decorations?: SourceControlResourceDecorations;
}

前の例は、ソース管理ビューに簡単なリストを表示するには十分ですが、ユーザーが各リソースに対して実行したい多くのユーザーインタラクションがあります。たとえば、ユーザーがリソース状態をクリックするとどうなりますか？リソース状態は、このアクションを処理するコマンドをオプションで提供できます。

export interface SourceControlResourceState {
  readonly command?: Command;
}

メニュー

ユーザーにより豊かなユーザーインターフェースを提供するために、メニュー項目を配置できる6つのソース管理メニューIDがあります。

scm/title メニューは、SCMビューのタイトルの右側にあります。navigation グループのメニュー項目はインラインで表示され、他のすべての項目は … ドロップダウンメニュー内に表示されます。

これら3つは同様です。

scm/resourceGroup/context はSourceControlResourceGroup 項目にコマンドを追加します。
scm/resourceState/context はSourceControlResourceState 項目にコマンドを追加します。
scm/resourceFolder/context は、SourceControlResourceState の resourceUri パスにフォルダが含まれ、ユーザーがリストビューモードではなくツリービューモードを選択している場合に表示される中間フォルダにコマンドを追加します。

メニュー項目を inline グループに配置すると、インラインで表示されます。他のすべてのメニュー項目グループは、通常マウスの右クリックでアクセスできるコンテキストメニューに表示されます。

SCMビューは複数選択をサポートしているため、コマンドは引数として1つ以上のリソースの配列を受け取ることに注意してください。

たとえば、Gitは、git.stage コマンドを scm/resourceState/context メニューに追加し、そのようなメソッド宣言を使用することで、複数のファイルをステージングすることをサポートしています。

stage(...resourceStates: SourceControlResourceState[]): Promise<void>;

SourceControl および SourceControlResourceGroup インスタンスを作成する際には、id 文字列の提供が必要です。これらの値は、それぞれ scmProvider および scmResourceGroup コンテキストキーに設定されます。メニュー項目の when 句でこれらのコンテキストキーを使用できます。Gitがgit.stage コマンドのインラインメニュー項目を表示できる方法は次のとおりです。

{
  "command": "git.stage",
  "when": "scmProvider == git && scmResourceGroup == merge",
  "group": "inline"
}

scm/sourceControl メニューは、ソース管理リポジトリビュー内の各 SourceControl インスタンスのコンテキストメニューです。

scm/change/title を使用すると、この後で説明するクイック差分インライン差分エディターのタイトルバーにコマンドを貢献できます。コマンドには、ドキュメントのURI、その中の変更の配列、およびインライン変更差分エディターが現在フォーカスしている変更のインデックスが引数として渡されます。たとえば、originalResourceScheme コンテキストキーが git と等しいことをテストする when 句とともにこのメニューに貢献される stageChange Gitコマンドの宣言を次に示します。

async stageChange(uri: Uri, changes: LineChange[], index: number): Promise<void>;

SCM入力ボックス

各ソース管理ビューの上部に位置するソース管理入力ボックスにより、ユーザーはメッセージを入力できます。操作を実行するために、このメッセージを取得 (および設定) できます。たとえばGitでは、これはコミットボックスとして使用され、ユーザーはコミットメッセージを入力し、git commit コマンドがそれを取得します。

export interface SourceControlInputBox {
  value: string;
}

export interface SourceControl {
  readonly inputBox: SourceControlInputBox;
}

ユーザーは、任意のメッセージを承認するために Ctrl+Enter (macOSでは Cmd+Enter) を入力できます。このイベントは、SourceControl インスタンスに acceptInputCommand を提供することで処理できます。

export interface SourceControl {
  readonly acceptInputCommand?: Command;
}

クイック差分

VS Codeは、クイック差分エディターガターの装飾の表示もサポートしています。これらの装飾をクリックすると、インライン差分エクスペリエンスが表示され、そこにコンテキストコマンドを貢献できます。

SCM quick diff

これらの装飾はVS Code自体によって計算されます。必要なのは、任意のファイルの元のコンテンツをVS Codeに提供することだけです。

export interface SourceControl {
  quickDiffProvider?: QuickDiffProvider;
}

QuickDiffProvider の provideOriginalResource メソッドを使用すると、メソッドに引数として提供されたリソースの Uri に一致する元のリソースの Uri をVS Codeに伝えることができます。

このAPIを、登録されたカスタム scheme に一致するUri が与えられた場合に、任意のコンテンツを提供できるworkspace 名前空間の registerTextDocumentContentProvider メソッドと組み合わせてください。

次のステップ

VS Codeの拡張性モデルについて詳しく知るには、次のトピックを参照してください。

SCM APIリファレンス - SCM APIの完全なドキュメントを参照
Git拡張機能 - Git拡張機能の実装を読んで学ぶ
拡張機能APIの概要 - VS Codeの完全な拡張性モデルについて学ぶ
拡張機能マニフェストファイル - VS Code package.json 拡張機能マニフェストファイルのリファレンス
貢献ポイント - VS Code 貢献ポイントのリファレンス

07/09/2025