소스 제어 API
소스 제어 API는 확장 작성자가 소스 제어 관리(SCM) 기능을 정의할 수 있도록 합니다. 슬림하면서도 강력한 API 표면을 통해 다양한 SCM 시스템을 Visual Studio Code에 통합하면서 모든 시스템에 대해 공통 사용자 인터페이스를 가질 수 있습니다.
VS Code 자체에는 Git 확장을 포함한 하나의 소스 제어 공급자가 포함되어 있으며, 이는 이 API에 대한 최고의 참고 자료이며 자체 SCM 공급자를 기여하고 싶다면 훌륭한 시작점입니다. Marketplace에는 SVN 확장과 같은 다른 훌륭한 예시도 있습니다.
이 설명서는 모든 SCM 시스템이 VS Code와 작동하도록 하는 확장을 구축하는 데 도움이 될 것입니다.
참고: 항상 설명서에서
vscode네임스페이스 API 참조를 참조할 수 있습니다.
소스 제어 모델
SourceControl은 리소스 상태, 즉 SourceControlResourceState 인스턴스로 소스 제어 모델을 채우는 책임이 있는 개체입니다. 리소스 상태는 자체적으로 그룹, 즉 SourceControlResourceGroup 인스턴스로 구성됩니다.
vscode.scm.createSourceControl을 사용하여 새 SourceControl을 만들 수 있습니다.
이 세 가지 개체가 서로 어떻게 관련되는지 더 잘 이해하기 위해 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는 작업 트리와 인덱스라는 두 가지 리소스 그룹을 정의합니다. 각 파일 변경은 해당 그룹 내에서 리소스 상태입니다.
- 인덱스 - 리소스 그룹
README.md, 수정됨 - 리소스 상태src/test/api.ts,src/api.ts에서 이름 변경됨 - 리소스 상태
- 작업 트리 - 리소스 그룹
.travis.yml, 삭제됨 - 리소스 상태README.md, 수정됨 - 리소스 상태
동일한 파일인 README.md가 두 개의 서로 다른 리소스 상태의 일부인 방법을 확인하세요.
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;
}
메뉴
사용자에게 훨씬 더 풍부한 사용자 인터페이스를 제공하기 위해 메뉴 항목을 배치할 수 있는 여섯 개의 소스 제어 메뉴 ID가 있습니다.
scm/title 메뉴는 SCM 보기 제목의 오른쪽에 있습니다. navigation 그룹의 메뉴 항목은 인라인으로 표시되고 다른 모든 항목은 … 드롭다운 메뉴 내에 표시됩니다.
이 세 가지는 유사합니다.
scm/resourceGroup/context는SourceControlResourceGroup항목에 명령을 추가합니다.scm/resourceState/context는SourceControlResourceState항목에 명령을 추가합니다.scm/resourceFolder/context는SourceControlResourceState의 resourceUri 경로에 폴더가 포함되어 있고 사용자가 트리 보기 모드를 목록 보기 모드보다 선호하는 경우 나타나는 중간 폴더에 명령을 추가합니다.
inline 그룹에 메뉴 항목을 배치하여 인라인으로 표시합니다. 다른 모든 메뉴 항목 그룹은 일반적으로 마우스 오른쪽 클릭을 사용하여 액세스할 수 있는 컨텍스트 메뉴에 표시됩니다.
SCM 보기가 다중 선택을 지원하므로 명령은 하나 이상의 리소스 배열을 인수로 받습니다.
예를 들어 Git는 scm/resourceState/context 메뉴에 git.stage 명령을 추가하고 다음과 같은 메서드 선언을 사용하여 여러 파일을 스테이징하는 것을 지원합니다.
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/repository 메뉴는 소스 제어 리포지토리 보기의 각 SourceControl 인스턴스에 대한 메뉴입니다. inline 그룹에 메뉴 항목을 배치하여 인라인으로 표시합니다. 다른 모든 메뉴 항목 그룹은 ... 메뉴에 표시됩니다. 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는 **빠른 비교** 편집기 여백 장식 표시도 지원합니다. 이러한 장식을 클릭하면 인라인 비교 환경이 표시되며, 여기에 컨텍스트 명령을 기여할 수 있습니다.
이러한 장식은 VS Code 자체에서 계산됩니다. 제공해야 하는 모든 것은 주어진 파일의 원본 내용을 VS Code에 제공하는 것입니다.
export interface SourceControl {
quickDiffProvider?: QuickDiffProvider;
}
QuickDiffProvider의 provideOriginalResource 메서드를 사용하여 구현은 메서드에 인수로 제공된 리소스의 Uri와 일치하는 원본 리소스의 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 기여 지점 참조