編集

ソース管理 API

ソース管理 API を使用すると、拡張機能の作成者はソース管理マネージメント (SCM) 機能を定義できます。これにより、多くの異なる SCM システムを Visual Studio Code に統合しながら、すべてに共通のユーザーインターフェイスを持たせることができる、スリムで強力な API サーフェスが提供されます。

VS Code SCM

VS Code 自体には Git 拡張機能というソース管理プロバイダーが同梱されており、これはこの 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 貢献ポイントのリファレンス

08/07/2025