Git에 흔적을 남기지 않는 방식
Skul은 파일을 생성하면서도 .gitignore, Git 이력, 인덱스는 건드리지 않습니다. 이를 위해 다음 세 가지 장치를 사용합니다.
캐시와 레지스트리
| 경로 | 저장 내용 |
|---|---|
~/.skul/library/ | 모든 프로젝트에서 재사용하는 번들 원본의 복제본 |
~/.skul/registry.json | 각 저장소에 적용할 구성과 각 워크트리에 실제로 작성한 내용 |
Skul은 저장소에 어떤 구성을 적용할지와 워크트리에 실제로 무엇을 작성했는지를 따로 기록합니다. 새 워크트리를 연결하면 적용할 구성을 바로 이어받고, skul apply를 실행할 때 파일을 작성합니다.
.gitignore 대신 로컬 제외 규칙
Skul은 생성한 파일을 .git/info/exclude에 등록합니다. 이 규칙은 내 로컬 복제본에만 적용되며 커밋하거나 푸시하지 않습니다. 번들을 제거하면 등록한 항목도 함께 지웁니다.
Skul은 작성한 모든 파일의 내용 지문도 기록합니다. 관리 중인 파일을 직접 수정했다면 제거하기 전에 확인을 요청하며, SKUL_NO_TUI=1일 때는 작업을 거부합니다. 수정한 내용을 아무 경고 없이 지우지 않기 위해서입니다.
루트 지침
AGENTS.md, CLAUDE.md, QWEN.md는 별도로 처리해야 합니다. 팀에서 이미 이 파일들을 커밋하고 있을 수 있기 때문입니다.
내 지침을 로컬에만 적용하려면 다음 세 가지를 지켜야 합니다.
- 변경 사항을 받아올 때는
skul sync를 사용하세요. 그 밖에HEAD를 이동하는 Git 명령을 실행할 때는, 실행 전에skul shadow --suspend를, 실행 후에 같은 명령을--refresh옵션으로 실행해야 합니다. - Skul이 관리하는 동안에는 파일을 직접 수정하지 마세요.
- 추적 중인 파일 하나의 섀도는 한 번에 한 번들만 관리할 수 있습니다.
추적하지 않는 파일
Skul이 파일을 작성하고 Git에서 숨기는 방식은 다른 파일과 같습니다. 로컬에 파일이 이미 있다면 그 내용을 원본으로 보관하고, SKUL:BUNDLE 마커로 구분해 번들 내용을 덧붙입니다. 여러 번들이 한 파일을 공유할 수 있고, 마지막 번들을 제거하면 원래 파일로 돌아갑니다.
원본에 내용을 덧붙이지 않고 통째로 바꾸려면 --root-instruction-mode replace를 사용하세요. 이 경우에도 번들을 제거하면 원본을 복원합니다.
추적 중인 파일: 섀도
Git이 이미 파일을 추적하고 있다면 제외 규칙만으로는 변경 사항을 숨길 수 없습니다. 그래서 Skul은 HEAD의 내용에 내 지침을 덧붙여 작업 파일을 만들고, skip-worktree를 설정합니다. git status는 변경 사항이 없는 상태를 유지하고, skul status에서는 섀도가 적용된 지침(Shadowed Instructions) 아래에 표시됩니다.
추적 중인 파일의 섀도는 한 번에 한 번들만 관리할 수 있습니다. Skul이 만들어 낸 결과물이므로 파일을 직접 수정하면 안 됩니다. 파일 내용이 Skul이 작성한 것과 달라지면 이후 명령은 덮어쓰기를 거부합니다.
업스트림 변경 사항 가져오기
skip-worktree는 업스트림의 변경 사항까지 숨깁니다. 따라서 HEAD를 이동하기 전에는 섀도를 중단하고, 작업이 끝나면 다시 적용해야 합니다.
skul sync
이 명령은 섀도를 중단한 뒤 git pull --ff-only를 실행하고, 끝나면 섀도를 다시 적용합니다. pull에 실패해도 먼저 섀도를 복원합니다. 업스트림에서 해당 파일의 추적을 중단했다면 섀도도 해제합니다.
다른 Git 명령은 앞뒤에 중단·갱신 명령을 직접 넣어 실행하세요.
skul shadow --suspend
git rebase origin/main
skul shadow --refresh
파일에 스테이징된 변경 사항, 스테이징하지 않은 변경 사항, 병합되지 않은 변경 사항이 있으면 Skul은 섀도를 생성하거나 갱신하지 않습니다.
정리
skul reset
이 워크트리에서 Skul이 관리하는 항목을 모두 제거합니다. 섀도가 적용된 파일은 HEAD의 내용으로 되돌리고, 따로 보관했던 로컬 원본도 복원합니다. git worktree remove 전에 실행하세요. 그렇지 않으면 레지스트리에 더 이상 존재하지 않는 복제본의 기록이 남습니다.