AmberTrail
개발 과정은 자동으로 기록하고, 남길 작업은 직접 선택하세요.
AmberTrail은 개발 중 디스크에 저장된 파일의 변화를 스냅샷으로 남기는 VS Code 확장 프로그램입니다. 작업 중간 상태를 타임라인에서 살펴보고, 변경 내용을 비교하거나 이전 상태로 복원할 수 있습니다. 남기고 싶은 시점을 선택하면 그때까지의 작업을 Git 커밋으로 정리할 수도 있습니다.
새로운 구현을 시도하기 전의 코드, 오류를 고치는 도중의 상태, 커밋하기에는 아직 이른 변경도 기록 대상으로 삼습니다. 직접 작성한 코드와 코딩 에이전트가 수정한 파일 모두 같은 파일 변경 감지 방식으로 기록합니다.
자동 기록과 작업 이름 생성은 로컬에서 동작합니다. 별도의 AI API 키, LLM 모델 설치, 코딩 에이전트 호출이나 추가 지시가 필요하지 않습니다.
주요 기능
| 기능 |
설명 |
| 자동 스냅샷 |
저장된 파일의 변경을 감지하고, 설정한 대기 시간에 따라 작업 상태를 기록합니다. |
| 작업 타임라인 |
날짜·작업 이름·시각·브랜치·변경 파일 수로 기록을 살펴봅니다. |
| 변경 비교 |
각 기록의 변경 목록과 파일별 Diff를 확인합니다. |
| 로컬 작업 이름 |
변경된 함수·클래스·설정 키·스타일 선택자를 분석해 제목을 만듭니다. 직접 이름을 지정할 수도 있습니다. |
| 복원과 복원 취소 |
현재 파일의 보호 백업과 변경 목록을 검토한 뒤 선택한 상태를 적용합니다. |
| 구간 커밋 |
선택한 스냅샷까지의 변경을 커밋하고, 파일별 포함·제외로 코드와 문서를 나누어 남깁니다. |
| 기록 관리 |
사이드바의 관리 팝업에서 기록 주기·저장 용량·일시 중지·정리·개별 삭제를 관리합니다. |
스냅샷에서 Git 커밋까지
스냅샷은 개발 도중의 상태를 촘촘하게 보관하고, Git 커밋은 사용자가 선택한 작업 구간을 프로젝트 이력으로 확정합니다. 자동 기록만으로 현재 브랜치·Git 인덱스·작업 파일이 바뀌지는 않습니다.
예를 들어 다음처럼 다섯 번의 기록이 쌓였다고 가정해 보세요.
개발 진행 스냅샷 1 → 스냅샷 2 → 스냅샷 3 → 스냅샷 4 → 스냅샷 5
선택한 시점 ↓ ↓
Git 이력 커밋 A 커밋 B
스냅샷 2를 선택하면 최초 비교 기준부터 2까지의 변경을 커밋합니다. 이후 스냅샷 5를 선택하면 앞서 커밋한 경계부터 5까지의 최종 변경을 다음 커밋으로 만듭니다. 그동안 작업 폴더에서 계속 진행한 최신 파일 내용은 유지합니다.
한 기록에 코드와 문서가 함께 있다면 문서를 제외하고 코드만 먼저 커밋할 수 있습니다. 남은 문서는 같은 기록에서 별도로 커밋할 수 있으며, 타임라인에는 일부 커밋 상태가 표시됩니다. 파일 단위로 선택하며, 한 파일 안의 일부 줄만 선택하는 기능은 제공하지 않습니다.
시작하기
실행 환경
| 항목 |
요구 사항 |
| 편집기 |
VS Code Desktop 1.95 이상 |
| 운영체제 |
로컬 Windows·macOS·Linux |
| Git |
2.43 이상, VS Code 내장 Git 확장 활성화 |
| Python |
3.12 이상, 사용자 환경에 별도 설치 |
| 작업 폴더 |
신뢰한 로컬 Git 저장소 |
현재 버전은 Remote SSH·WSL·개발 컨테이너·웹·가상 워크스페이스를 지원하지 않습니다. Python 실행 환경은 확장에 포함되어 있지 않으며, Python 코어에는 서드파티 패키지가 필요하지 않습니다.
설치와 첫 기록
- 배포받은
.vsix 파일을 VS Code의 Extensions: Install from VSIX... 명령으로 설치합니다.
- 로컬 Git 저장소를 열고 작업 폴더를 신뢰합니다.
- 사이드바의 AmberTrail 아이콘을 열어 기록 상태를 확인합니다.
- 파일을 수정해 저장합니다. 기본 설정에서는 변경이 멈춘 뒤 5초가 지나면 자동 기록을 시도합니다. 새 기록 버튼으로 즉시 기록할 수도 있습니다.
처음 열었을 때 이미 수정되었거나 새로 생성된 파일이 있다면, 현재 HEAD와 비교한 변경으로 첫 기록을 표시합니다. 변경이 없는 깨끗한 시작 상태는 내부 비교 기준으로만 보관하므로 타임라인에 빈 기록이 생기지 않습니다.
Python 실행 파일 지정
기본적으로 Windows에서는 python, macOS/Linux에서는 python3를 실행합니다. 다른 실행 파일이나 가상환경을 사용하려면 VS Code의 사용자 설정에 경로를 지정하고 창을 다시 로드하세요.
{
"devSnapshot.pythonPath": "C:\\path\\to\\venv\\Scripts\\python.exe"
}
macOS/Linux의 가상환경 경로 예시는 /path/to/venv/bin/python입니다. 프로젝트에서 선택한 Python 인터프리터를 자동으로 사용하지는 않습니다.
타임라인 사용하기
기록 확인과 이름 지정
기록을 펼치면 저장 당시의 브랜치·HEAD와 변경된 파일을 확인할 수 있습니다. 변경 비교로 해당 기록의 전후 내용을 살펴보고, 파일을 선택하면 개별 Diff를 엽니다. 밝은·어두운·고대비 테마를 지원하며, 펼친 상태는 창을 다시 열어도 유지합니다.
자동 제목이 충분하지 않다면 이름 변경으로 작업의 의미를 직접 적을 수 있습니다. 직접 지정한 이름은 자동 제목보다 우선하고 커밋 메시지 초안에도 사용됩니다. 이름을 비우면 자동 제목으로 돌아갑니다. 오래 보관할 시점은 기록 고정으로 보호할 수 있습니다.
이전 상태로 복원
복원을 선택하면 현재 파일의 보호 백업을 만들고 생성·수정·삭제될 파일을 보여줍니다. Diff를 확인한 뒤, 코딩 에이전트나 빌드 도구처럼 파일을 수정하는 외부 프로세스를 멈추고 최종 승인하면 적용됩니다.
복원은 파일 내용을 되돌리며 현재 Git 브랜치·HEAD·인덱스는 유지합니다. AmberTrail: Undo Last Restore 명령으로 직전 복원을 되돌릴 수 있고, 이때도 현재 상태를 다시 검토하고 백업합니다.
선택한 시점까지 커밋
- 커밋할 기록을 펼칩니다.
- 파일 목록의 **− / +**로 제외·포함할 파일을 선택합니다. 선택 상태는 새로고침과 재시작 후에도 유지됩니다.
- 커밋을 눌러 포함·제외 목록을 검토하고 준비를 승인합니다.
- Git 변환이 적용된 실제 커밋 대상 Diff를 확인한 뒤 최종 승인합니다.
커밋 준비는 저장소 밖의 별도 작업 폴더와 인덱스에서 진행합니다. 성공하면 현재 브랜치의 HEAD와 인덱스가 커밋 결과로 갱신됩니다. 선택 시점의 대상 파일을 모두 커밋한 경우에는 같은 브랜치의 이전 기록을 정리할지 별도로 검토할 수 있습니다.
원격에 올릴 때는 AmberTrail: Review and Push 명령으로 원격·브랜치·정확한 커밋 OID를 검토한 뒤 승인합니다. 자동 기록 과정에서 Push를 실행하지 않습니다.
기록 주기와 저장 용량 관리
저장소의 관리 버튼을 누르면 사이드바 안에 관리 팝업이 열립니다. 명령 팔레트의 AmberTrail: 기록 주기 설정으로도 같은 팝업을 열 수 있습니다.
| 주기 |
기본값 |
팝업 변경 단위 |
동작 |
| 파일 변경 후 기록 대기 |
5초 |
5초 |
마지막 변경 후 이 시간 동안 추가 변경이 없으면 기록을 시도합니다. |
| 연속 편집 중 최대 기록 대기 |
1분 |
1분 |
변경이 계속되어도 첫 변경부터 이 시간이 지나면 기록을 시도합니다. |
| 전체 파일 내용 확인 |
10분 |
5분 |
관리 대상 파일을 다시 읽고 내용 해시를 확인해 누락된 변경을 찾습니다. |
세 값을 입력하고 주기 저장을 누르면 재로드 없이 적용됩니다. 실행 중인 캡처가 있다면 먼저 취소한 뒤 새 설정을 적용합니다. Escape 또는 닫기로 나가면 저장하지 않은 입력은 반영하지 않습니다.
전체 파일 내용 확인은 디스크 파일의 변경 여부를 재확인하는 작업입니다. 프로그램의 테스트 실행이나 저장된 전체 이력의 무결성 검사를 뜻하지 않습니다. 변경이 없으면 정해진 시간이 지나도 같은 스냅샷을 반복 생성하지 않습니다. 파일이 계속 바뀌거나 다른 작업으로 기록이 제한된 상태에서는 실제 기록 완료가 늦어질 수 있습니다.
같은 팝업에서 저장 용량을 확인하고, 자동 기록을 일시 중지·재개하거나 보존 정책에 따라 기록을 정리할 수 있습니다. 개별 삭제는 대상과 보호 여부를 확인한 뒤 최종 승인을 거칩니다.
고급 설정
VS Code 설정에서 devSnapshot을 검색해 세부 값을 조정할 수 있습니다. 기록 주기는 설정 파일에서 모두 초 단위로 입력합니다.
| 설정 |
기본값 |
의미 |
devSnapshot.idleSeconds |
5 |
변경이 멈춘 뒤 기록까지 기다리는 시간 |
devSnapshot.maxIntervalSeconds |
60 |
연속 편집 중 기록 시도까지의 최대 대기 시간 |
devSnapshot.fullHashSeconds |
600 |
전체 파일 내용 해시를 다시 확인하는 주기 |
devSnapshot.reconcileSeconds |
120 |
감시에서 놓친 변경을 찾는 파일 목록·메타데이터 보조 스캔 주기 |
devSnapshot.maxFileMiB |
10 |
기록할 단일 파일의 최대 크기 |
devSnapshot.retentionDays |
30 |
일반 기록 보존 기간 |
devSnapshot.maxSnapshots |
1000 |
일반 스냅샷 개수 한도 |
devSnapshot.maxStorageMiB |
2048 |
저장소별 기록 용량 한도 |
devSnapshot.exclude |
[] |
추가로 제외할 파일·경로 패턴 |
관리 팝업에서 저장하는 주기는 해당 작업 폴더 설정에 반영됩니다. 보존 한도에 도달하면 보호되지 않은 오래된 기록부터 정리합니다. 최신 기록·고정 기록·활성 작업 구간의 초기 기준·브랜치별 최신 커밋 경계·미완료 작업의 복구 기록은 보호됩니다. 복원과 커밋 준비의 백업은 최소 7일 동안 보호합니다. 보호 기록만으로 용량 한도를 넘으면 기록을 중단하고 정리를 요청합니다.
작동 원리
1. 파일 변경을 모아 캡처 시점을 결정합니다
VS Code의 파일 감시와 저장 이벤트로 변경 경로를 수집합니다. Python 스케줄러는 마지막 변경 시각과 첫 변경 시각을 기준으로 캡처 시점을 결정합니다.
일반적인 변경은 수집한 경로를 중심으로 증분 처리합니다. 이벤트 누락을 보완하기 위해 기본 2분 주기로 파일 목록과 메타데이터를 살피며, 이미 감지한 변경의 기록을 기다리는 동안에는 이 보조 스캔이 설정한 대기 시간을 앞당기지 않습니다. 별도의 전체 해시 확인은 기본 10분 주기로 실행합니다.
캡처는 백그라운드 작업으로 진행합니다. 파일과 Git 상태가 캡처 도중 달라졌는지 확인하고, 안정된 결과를 얻지 못하면 기록을 재시도하거나 지연 상태를 표시합니다. 여러 파일을 정확히 같은 순간에 읽는 방식은 아닙니다.
2. 파일 내용과 시점 정보를 나누어 저장합니다
파일 내용은 SHA-256 해시를 주소로 사용하는 객체로 저장하고 gzip으로 압축합니다. 동일한 내용은 기존 객체를 재사용합니다. 각 스냅샷은 파일 경로·객체 해시·파일 상태·브랜치·HEAD·기록 시각 등을 담은 독립 JSON manifest를 가집니다.
즉, 매번 작업 폴더를 통째로 복사하거나 이전 Diff를 차례대로 재생하는 대신, 해당 시점의 파일 목록이 필요한 내용 객체를 참조합니다. 같은 작업 구간에서 파일 상태가 같으면 새 스냅샷을 만들지 않습니다.
VS Code 확장 전용 저장 공간 / repositories / <worktree-id> /
identity.json 저장소 식별 정보
objects/ 해시로 식별하는 압축 파일 내용
snapshots/ 시점별 파일 상태와 객체 참조
epochs/ 브랜치·HEAD 변경에 따른 작업 구간의 기준
metadata/ 사용자 지정 제목·고정 등 부가 정보
receipts/ 커밋 결과와 다음 커밋의 기준
operations/ 복원·커밋 작업의 진행 및 복구 정보
저장 위치는 작업 저장소 밖의 VS Code globalStorageUri/repositories/<worktree-id>입니다. 같은 Git 공통 디렉터리를 사용하는 Worktree도 별도 ID로 관리합니다. 파일 내용과 manifest의 해시를 확인하며, 손상되었거나 알 수 없는 형식의 기록을 발견하면 복원·정리를 중단합니다.
3. 브랜치와 HEAD를 비교 기준으로 사용합니다
브랜치 또는 HEAD가 바뀌면 새로운 작업 구간(epoch)을 만듭니다. 구간의 첫 기록은 저장 당시 HEAD와 비교하고, 이후 기록은 직전 스냅샷과 비교합니다. 새 초기 기록에는 비교에 필요한 HEAD의 원본 내용도 보존합니다.
이 구분을 통해 브랜치를 옮기거나 커밋한 뒤 생긴 첫 변경을 이전 작업 구간의 파일과 혼동하지 않고 표시합니다. 과거 버전의 기록은 보존된 정보에 따라 Git의 기존 HEAD 객체가 비교에 필요할 수 있습니다.
4. 저장된 변경에서 작업 이름을 만듭니다
제목은 파일명뿐 아니라 저장된 전후 내용의 차이를 로컬 규칙으로 분석해 생성합니다.
| 분석 대상 |
사용하는 정보 |
제목 예시 |
| Python |
AST로 찾은 함수·클래스의 변화 |
로그인 검증 함수 수정 |
| JavaScript·TypeScript |
이름 있는 함수·클래스·메서드·블록 화살표 함수의 변화 |
인증 검증 함수 수정 |
| JSON |
변경된 설정 키 |
scripts.build 설정 수정 |
| CSS·SCSS |
변경된 선택자 |
.login-form 스타일 수정 |
| 그 외 |
파일명과 추가·수정·삭제 상태 |
common.py·git.py 수정 |
예를 들어 validate_login 함수의 본문이 바뀌면 알려진 식별자 단어와 변경 종류를 조합해 제목을 만듭니다. 프로젝트의 전체 의도나 기능 완성도를 판단하는 의미 분석은 제공하지 않으며, 자동 제목이 테스트 성공을 뜻하지도 않습니다.
분석 비용을 제한하기 위해 최대 12개 파일, 파일의 각 버전 64 KiB, 합계 512 KiB까지만 읽습니다. 큰 파일·바이너리·지원하지 않는 문법은 파일명 요약으로 표시합니다. 기존 스냅샷은 원본 manifest를 다시 쓰지 않고 표시 제목을 갱신하며, 직접 지정한 이름을 우선합니다.
이전 Codex 보고 연동은 선택 기능으로 남아 있습니다. devSnapshot.showAgentReports를 켜면 관련 UI를 볼 수 있지만 보고 내용은 스냅샷 제목에 사용하지 않습니다. 자세한 내용은 Codex 연동 기록을 참고하세요.
프로그램 구조
AmberTrail은 VS Code 화면과 사용자 조작을 담당하는 TypeScript 확장과 파일 기록·복원·Git 작업을 담당하는 Python 코어로 구성됩니다.
VS Code
├─ 사이드바 타임라인 · 관리 팝업
├─ Diff 문서 · 명령 · 승인 화면
└─ 파일 감시 · Git 저장소 상태 연결
│
TypeScript 확장 호스트
│
JSON-RPC 2.0 / 표준 입출력
│
Python 백그라운드 프로세스
├─ 기록 스케줄러 · 제외 정책 · 로컬 제목 생성
├─ 스냅샷 객체 저장소 · 보존 정책
└─ 복원 · 구간 커밋 · 중단 후 복구
│ │
확장 전용 저장 공간 파일시스템 · Git CLI
통신은 확장이 실행한 Python 프로세스의 개인 표준 입출력 파이프로만 이루어집니다. HTTP 서버나 외부 수신 포트를 열지 않습니다. Python은 -I -S 격리 모드로 실행해 프로젝트 모듈·PYTHONPATH·site 패키지를 불러오지 않습니다.
사용자 승인은 TypeScript 화면에서 받고, Python은 실행 직전 파일·Git·미저장 편집 상태를 다시 확인합니다. 연결이 끊기면 복원·커밋 같은 변경 명령을 자동 재전송하지 않습니다.
| 위치 |
역할 |
src/extension.ts |
확장 활성화, 파일 감시, 명령과 승인 흐름 |
src/timelineView.ts, media/timeline.js, media/timeline.css |
타임라인과 관리 팝업, 화면과 확장 호스트 사이의 메시지 처리 |
src/management.ts, src/presentation.ts |
관리 입력 검증, 기록 제목·시각·브랜치 표시 |
src/bridge.ts, src/protocol.ts |
Python 프로세스 통신과 메시지 타입 |
src/documents.ts |
읽기 전용 검토 문서와 Diff |
backend/dev_snapshot/engine.py, rpc.py |
저장소 세션, 기록 스케줄러와 JSON-RPC 요청 처리 |
backend/dev_snapshot/snapshots.py, local_summary.py |
캡처, 제외 정책, 변경 비교와 로컬 제목 생성 |
backend/dev_snapshot/store.py, common.py |
객체·manifest 저장, 무결성 확인, 잠금과 보존 정책 |
backend/dev_snapshot/restore.py, restore_io.py |
복원 계획, 보호 백업, 파일 교체와 복구 |
backend/dev_snapshot/boundary.py, commits.py, git.py |
구간 커밋, 인덱스 관리, Git CLI와 Push |
기록 범위와 데이터 보호
기록 대상은 저장소 안의 추적 파일과 Git에서 무시하지 않는 미추적 일반 파일입니다. 바이너리도 파일 크기 한도 안에서 원본 바이트로 저장합니다. .gitignore·Git 전역 ignore·.git/info/exclude는 Git의 판정을 따르며, 이미 추적 중인 파일은 Git ignore에 추가하는 것만으로 제외되지 않습니다.
.env·.env.*·*.pem·*.key·*.p12·*.pfx·id_rsa·id_ed25519·.npmrc·.pypirc는 추적 여부와 관계없이 기본 제외합니다. 링크·junction·특수 파일·중첩 저장소·Submodule·Python 가상환경 내부도 기록 범위에서 제외합니다.
추가 제외는 devSnapshot.exclude로 설정합니다. /가 없는 패턴은 파일명에, /가 있는 패턴은 전체 상대 경로에 적용하는 Python fnmatch 규칙입니다. 경로 패턴의 *는 /도 포함하며 숨김 파일에도 적용됩니다.
민감 파일의 기본 차단을 해제하려면 사용자 설정의 devSnapshot.allowSensitiveFiles에 허용 패턴을 명시해야 합니다. 작업 폴더 설정으로는 해제할 수 없고, 허용 패턴도 Git ignore와 추가 제외 설정을 우회하지 않습니다. 예제 파일 역시 이름이 기본 제외 규칙에 걸리면 명시적으로 허용해야 합니다.
백그라운드 기록·조회·제목 생성은 네트워크를 사용하지 않습니다. 다만 승인한 Git 커밋의 필터·훅·서명 도구와 Push는 해당 도구의 동작을 따릅니다. 저장 내용은 gzip 압축이며 암호화하지 않습니다. 파일명 규칙으로 모든 비밀 정보를 식별할 수는 없으므로 기록 범위를 확인하세요. 제외 설정을 바꾸어도 과거 기록은 삭제되지 않습니다.
복구와 사용 범위
복원과 커밋 준비는 진행 상황을 작업 journal에 남깁니다. 도중에 강제 종료되면 복구 검토에서 이전 상태 복구, 보호 백업 내보내기, 직접 해결 후 완료 처리를 선택할 수 있습니다. 미완료 작업이 있으면 복구를 검토할 때까지 자동 기록과 새 변경 작업을 제한합니다.
동일한 저장소는 OS 파일 잠금으로 한 프로세스만 기록합니다. 다른 VS Code 창에서는 저장된 이력을 읽기 전용으로 조회할 수 있습니다.
사용할 때 다음 범위를 확인하세요.
- 디스크에 저장한 내용만 기록합니다. 미저장 에디터 버퍼를 보관하거나 자동 저장하지 않습니다.
- 외부 백업은 별도로 필요합니다. 디스크 장애나 VS Code 사용자 데이터 삭제로 로컬 기록도 없어질 수 있습니다.
- 복원 전 외부 쓰기 작업을 멈춰야 합니다. 여러 파일의 원자적 캡처·복원을 보장하지 않으며, 감지된 외부 수정은 강제로 덮어쓰지 않습니다.
- 커밋에는 비어 있는 Staging 영역이 필요합니다. 기존 Staging·부분 Staging·intent-to-add가 있으면 제한합니다. detached HEAD나 다른 브랜치의 기록도 커밋 대상으로 사용할 수 없습니다.
- 기록만으로 정상 동작을 검증하지 않습니다. 테스트 실행·성공 판정은 자동 기록과 별개이며 기본 검증 상태는 미검증입니다.
- 대규모 저장소는 초기 기록에 시간이 걸릴 수 있습니다. Windows의 10,000개 파일·약 100 MiB 측정에서는 초기 캡처가 약 128초, 10개 파일 증분 캡처가 약 1.57초였습니다. 환경별 차이와 측정 한계는 성능 보고서를 참고하세요.
복원·Git 작업의 세부 제약과 중단 후 처리
- 복원에는 작업 파일이 있는 파일시스템의 하드 링크 지원이 필요합니다. 지원하지 않으면 원본을 교체하기 전에 중단합니다. 파일 바이트와 실행 권한을 복원하며 ACL·소유권·타임스탬프·하드링크 관계는 복원하지 않습니다. 새 교체 파일은 소유자 접근 권한으로 생성합니다.
- 다른 브랜치·Worktree로의 복원은 제한합니다. 같은 브랜치에서 HEAD가 진행된 경우에는 Diff 검토 후 복원할 수 있습니다. Windows/macOS에서 대소문자만 다른 경로가 겹치는 복원은 차단합니다. 제외 파일과 한 번도 관리하지 않은 새 파일은 보존하며, 관리 파일 삭제는 승인 목록과 백업에 포함됩니다.
- 교체 직전의 실제 파일은 같은 부모 폴더의
.dev-snapshot-<ID>.restore에 먼저 보존합니다. 교체 중 같은 경로에 새 파일이 생기면 덮어쓰지 않고 중단합니다. 충돌이 남으면 복구 화면에서 보존 폴더를 확인하고 원본·교체본·현재 파일을 경로 정보와 함께 내보낼 수 있습니다. 직접 해결 처리 후에도 보존 폴더는 자동 삭제하지 않으며, 이 폴더의 용량은 스냅샷 저장 한도에 포함하지 않습니다.
- 복원 실패 시 확장이 쓴 내용과 여전히 일치하는 파일만 되돌립니다. 외부 수정이나 Git 컨텍스트 변화가 있으면 강제로 복구하지 않습니다. 커밋 실패·취소 시 인덱스 복구도 준비한 상태가 유지될 때만 수행합니다.
- 외부 커밋으로 HEAD가 바뀌면 이후 새 스냅샷을 기준으로 커밋해야 합니다. 이미 완료한 커밋 경계 이전의 기록은 다시 커밋할 수 없으며, 부분 커밋한 같은 경계의 남은 파일은 선택할 수 있습니다.
- Git 필터·줄바꿈 변환으로 실제 커밋 내용이 스냅샷 바이트와 달라질 수 있습니다. Git 훅과 서명 설정을 유지하지만, 별도 준비 폴더에는 무시된 의존성·로컬 환경 파일이 없어 훅이 실패할 수 있습니다. 훅이 검토한 트리를 바꾸면 자동 reset·amend하지 않고 복구 검토를 요구합니다.
- 강제 종료로 남은 Git
index.lock은 자동 삭제하지 않습니다. 실행 중인 Git 프로세스와 현재 HEAD·인덱스를 확인한 뒤 처리해야 합니다. Python 연결이 끊기면 창을 다시 로드하고 기록·Git 상태·복구 journal을 검토하세요.
- sparse checkout과 partial clone은 지원하지 않습니다. Git LFS는 디스크에 있는 실파일만 크기 정책에 따라 기록하며 LFS 원격 서버를 백업하지 않습니다. 강제 Push·자동 fetch/rebase·태그 일괄 Push는 실행하지 않습니다.
개발과 검증
Node.js 22와 Python 3.12 이상을 준비한 뒤 실행합니다.
npm ci
npm run check
npm test
npm run build
VS Code에서 이 저장소를 열고 F5의 Run AmberTrail을 실행하면 확장 개발 창이 열립니다. 그 창에서 기록할 Git 저장소를 여세요. 저장소에 log_venv가 있으면 개발 모드와 Python 실행 스크립트가 우선 사용하며, 가상환경은 Git과 배포 패키지에서 제외합니다. 다른 Python으로 테스트하려면 DEV_SNAPSHOT_PYTHON 환경 변수에 실행 파일을 지정합니다.
| 명령 |
용도 |
npm run check |
TypeScript 타입 검사 |
npm run test:python |
임시 Git 저장소를 사용하는 Python 코어 테스트 |
npm run test:bridge |
Python 통신과 확장 명령 테스트 |
npm run test:integration |
별도 VS Code 환경에서 활성화·파일 기록 등 통합 테스트 |
npm run benchmark |
10,000개 파일의 초기·증분 캡처 성능 측정 |
npm run package |
로컬 설치용 ambertrail-0.2.5.vsix 생성 |
통합 테스트는 별도 사용자 데이터·확장 디렉터리를 사용합니다. 기본적으로 테스트용 VS Code를 다운로드하며, 기존 실행 파일은 VSCODE_EXECUTABLE_PATH로 지정합니다. VSCODE_VERSION=1.95.0으로 지원 하한을 검사할 수 있습니다. 패키징은 Marketplace 게시를 실행하지 않으며, Python 코어 소스는 포함하고 Python 실행 환경·테스트 데이터는 제외합니다.
Python 테스트는 복원 바이트·인덱스 보존·제외 정책·객체 손상·외부 수정·강제 종료·Git 훅·Worktree 등을 다룹니다. Node 테스트는 통신·명령·설정 저장을, VS Code 테스트는 활성화·디스크 기록·미저장 편집 분리를 다룹니다. 모든 승인 대화상자를 자동 조작하는 테스트는 포함하지 않습니다.
CI는 Windows·macOS·Linux와 VS Code 1.95/최신 안정 버전을 대상으로 구성되어 있으며, 별도 Git 2.43 코어 테스트도 있습니다. 이는 검증 구성에 대한 설명이며 모든 환경의 실행 결과를 보장하는 표시는 아닙니다.
관련 문서와 라이선스
Marketplace 게시자 ID는 amber8800, 확장 ID는 amber8800.dev-snapshot입니다. 화면에는 AmberTrail로 표시하며, 명령·설정 접두사는 devSnapshot.*를 사용합니다.
이전 시험 설치의 확장 ID dev-snapshot.dev-snapshot과는 별도 확장으로 인식됩니다. 확장 전용 저장 공간도 달라 기존 기록을 자동으로 이전하지 않습니다. 기존 기록이 필요하면 이전 설치의 저장 데이터를 보존하세요.
