ソース管理 API

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

VS Code SCM

VS Code 自体には、1 つのソース管理プロバイダーである Git 拡張機能が同梱されています。これはこの API の最良のリファレンスであり、独自の SCM プロバイダーをコントリビューションしたい場合の優れた出発点となります。 Marketplace には、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 を VS Code に伝えることができます。

この API を workspace 名前空間の registerTextDocumentContentProvider メソッドと組み合わせます。これにより、登録されたカスタム scheme に一致する Uri を指定して、任意のリソースのコンテンツを提供できます。

次のステップ

VS Code の拡張機能モデルの詳細については、次のトピックをお試しください

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

04/03/2025