작동 방식

dotweave의 동작 원리와 설계 철학을 알아보세요.

내부 동작을 이해하면 dotweave를 더 예측 가능하게 사용할 수 있어요. 이 가이드에서는 멘탈 모델, push와 pull의 데이터 흐름, 그리고 설계 결정들을 다뤄요.

멘탈 모델

dotweave는 로컬 설정 파일과 Git으로 추적되는 sync 디렉터리 사이의 양방향 미러라고 생각하면 돼요:

로컬 파일이 작업 중에는 원본(source of truth)이에요.
sync 디렉터리는 Git 리모트에 push하고 다른 기기에서 pull할 수 있는 미러예요.

dotweave는 뒤에서 몰래 파일을 수정하지 않아요. push로 미러를 업데이트하거나 pull로 미러의 변경사항을 적용하는 걸 직접 실행해야 해요.

데이터 흐름

에디터 → 로컬 파일 → dotweave push → sync 디렉터리 → git push → 리모트
                                                                    ↓
다른 기기 ← dotweave pull ← sync 디렉터리 ← git pull ← 리모트

두 가지 별도의 작업이 있어요. Git 전송은 그 사이에 위치하지만 전적으로 사용자가 관리해요.

Push 흐름

manifest.jsonc 로드: dotweave가 설정 파일을 읽어 추적 중인 모든 파일과 설정을 파악해요.
로컬 파일 탐색: 각 항목에 대해 현재 플랫폼에 맞는 localPath의 파일을 읽어요.
기존 파일과 비교: sync 디렉터리의 파일이 이미 동일하면 아무것도 쓰지 않아요.
시크릿 암호화: secret으로 표시된 항목은 age로 암호화한 뒤 저장해요.
파일 쓰기: (암호화된 경우도 포함해서) 내용을 sync 디렉터리의 repoPath에 써요.

Pull 흐름

manifest.jsonc 로드: 같은 설정 파일, 같은 해석 방식.
파일 읽기: sync 디렉터리에서 각 파일을 읽어요.
시크릿 복호화: 암호화된 파일은 로컬 age 키로 복호화해요.
로컬 경로에 쓰기: 내용을 해석된 localPath에 써요.
퍼미션 적용: 설정 파일에 기록된 파일 퍼미션을 복원해서 실수로 모든 사용자가 읽을 수 있게 되는 걸 방지해요.

설계 결정

로컬 우선

에디터가 디스크의 실제 파일에 쓰고, dotweave는 같은 파일을 읽어요. 데이터베이스도, 데몬도, 백그라운드 감시자도 없어요. 동기화 시점은 사용자가 정해요.

심링크 없음

일부 dotfile 관리 도구는 설정 파일을 저장소 안의 파일을 가리키는 심링크로 대체해요. dotweave는 의도적으로 파일을 복사하는 방식을 택했어요. 퍼미션 문제, 파일 시스템 간 이슈, 심링크를 따라가지 못하는 도구로 인한 의외의 상황을 피할 수 있어요.

age 암호화

시크릿은 sync 디렉터리에서 age로 암호화된 상태로 저장돼요. 단순함 때문에 age를 선택했어요. 키 파일 하나면 되고, 키 서버도 없고, 만료 관리도 없어요. 비밀 키는 절대 기기 밖으로 나가지 않아요.

Git을 전송 수단으로

dotweave는 자체 동기화 프로토콜을 만드는 대신 Git에 올라타요. 브랜치, 히스토리, merge 충돌 도구, 호스팅(GitHub, GitLab 등)을 공짜로 사용할 수 있어요.

sync 디렉터리 구조

sync 디렉터리는 예측 가능한 레이아웃을 가진 일반 Git 저장소예요. 전체 내용은 디렉터리 구조 가이드를 참고하세요.

간략하게 보면:

~/dotfiles/          ← sync 디렉터리 루트 (Git repo)
├── manifest.jsonc   ← 추적 중인 모든 파일이 나열된 설정 파일
├── .age-key         ← age 비밀 키 (git-ignored)
├── .age-recipients  ← 암호화를 위한 age 공개 키
└── ...              ← dotweave push로 생성된 파일들