편집 기록을 Git으로 내보내기
VMark는 문서마다 편집 기록을 남깁니다. 저장할 때마다, 그리고 AI 클라이언트가 MCP로 편집할 때마다 누가 했는지와 함께 기록됩니다. 파일 → 문서 기록 → 편집 기록을 Git으로 내보내기… 는 이 기록을 Git 저장소로 복사하므로, git log로 살펴보거나 비교하거나 프로젝트와 함께 보관할 수 있습니다.
내보내는 방법
- 기록을 내보낼 문서를 엽니다.
- 파일 → 문서 기록 → 편집 기록을 Git으로 내보내기… 를 선택합니다(또는 명령 팔레트에서 편집 기록을 Git으로 내보내기 를 실행합니다).
- Git 저장소 안의 폴더를 고릅니다. 선택 창은 문서가 있는 폴더에서 열립니다.
VMark는 추가한 커밋 수를 알려 주거나, 브랜치가 이미 최신 상태였다고 알려 줍니다.
브랜치에 담기는 내용
기록은 전용 브랜치 vmark-journal/<document-uuid> 로 갑니다. VMark는 작업 트리, 인덱스, HEAD, 다른 브랜치를 절대 건드리지 않으며 브랜치를 전환하지도 않습니다. 브랜치에는 문서 이름의 파일 하나만 들어 있습니다.
- 리비전마다 커밋 하나. 작성자는 편집한 사람(사용자 또는 AI 클라이언트)이고, 날짜는 편집한 시각입니다.
- 정리된 기록 구간마다 요약 커밋 하나. VMark는 기록을 작게 유지하려고 오래된 리비전을 정리합니다. 정리된 리비전이 이어진 구간은 Collected history 라는 커밋 하나가 되며, 그 구간에서 편집한 모든 사람을 나열합니다.
각 커밋 메시지 끝에는 VMark와 연결해 주는 트레일러가 붙습니다.
| 트레일러 | 의미 |
|---|---|
VMark-Document | 문서의 식별자. 모든 커밋에서 같습니다 |
VMark-Revision | 이 커밋이 기록하는 리비전 |
VMark-Parent | 바로 앞 리비전 |
VMark-Actor | 편집한 사람 |
VMark-Kind | 기록된 방식: controlled(VMark를 통한 AI 편집), observed(저장), gap(VMark 밖에서 일어난 변경) 등 |
VMark-Tool | AI 편집에 쓰인 MCP 도구 |
VMark-Session, VMark-Client | AI 클라이언트가 알려 준 세션 라벨과 이름 |
VMark-Collected | 요약 커밋에서, 포함하는 정리된 리비전의 범위 |
VMark-Actors | 요약 커밋에서, 그 범위에서 편집한 모든 사람(정렬됨) |
다시 내보내기
원하는 만큼 여러 번 내보낼 수 있습니다. 다음 내보내기는 지난번 이후의 리비전만 추가하고, 새로운 것이 없으면 아무것도 바꾸지 않습니다. 같은 기록은 항상 같은 커밋을 만듭니다.
브랜치가 VMark가 남겨 둔 상태가 아니면, VMark는 덮어쓰지 않고 내보내기를 거부합니다.
- 마지막 내보내기 이후 브랜치가 바뀌었습니다(누군가 커밋했거나, 되돌렸거나, 다시 썼습니다). 브랜치를 옮기거나 삭제한 뒤 다시 내보내세요.
- 같은 이름의 브랜치가 있지만 이 문서의 VMark 내보내기가 아닙니다.
- 브랜치가 체크아웃되어 있습니다(워크트리에서).
요구 사항과 제한
- Git이 설치되어 있어야 합니다. VMark는 로그인 셸의
PATH에서 Git을 찾고, 없으면 내보내기가 그렇게 알려 줍니다. - 저장된 기록만 내보냅니다. 아직 저장하지 않은 편집은 포함되지 않습니다.
- VMark는 Git의 저수준 명령으로 커밋을 만들기 때문에 커밋 훅은 실행되지 않습니다. 브랜치 갱신을 감시하는 훅은 실행됩니다.
- 기록이 크면 시간이 걸립니다. 커밋 하나마다 Git 프로세스가 몇 개씩 실행됩니다.
- 얕은 복제(shallow clone)에서는 VMark가 이 컴퓨터에서 직접 내보낸 브랜치만 이어 갑니다.
- 내보내는 동안에는 내보내기 브랜치를 체크아웃하지 마세요. 마지막 워크트리 확인 이후에 체크아웃하면 그 워크트리의 인덱스와 파일이 이동된 브랜치와 어긋난 상태로 남을 수 있습니다.