manifest.jsonc

위치와 버전

manifest.jsonc는 sync 디렉터리 루트에 있어요. 즉 커밋되어 모든 기기가 공유하는 파일이에요. dotweave가 무엇을 추적할지는 이 파일 하나가 결정해요.

현재 버전은 8이에요. 버전 7도 받아들여서 제자리에서 마이그레이션하고, 그전에 manifest.jsonc.v7.bak 백업을 먼저 써요. 버전 7은 프로필 이름을 항목에만 저장했고, 마이그레이션이 이를 최상위 profiles 레지스트리로 끌어올려요. 8보다 높은 버전이면 명령이 실패해요.

파일 형식은 JSONC라서 손으로 편집할 때 //와 /* */ 주석을 남길 수 있어요. 옆에 manifest.json 파일이 있으면 읽지 않고 거부해요.

dotweave track, dotweave untrack, dotweave profile add|remove를 실행하면 dotweave가 이 파일을 다시 써요. 손으로 넣은 주석과 키 순서는 재작성 과정에서 보존되지 않아요.

최상위 필드

dotweave는 이 키들을 version, repositoryFormat, age, profiles, entries 순서로 직렬화해요.

항목 필드

항목 하나는 홈 디렉터리 아래에 있는 추적 대상 파일이나 디렉터리 하나를 나타내요.

항목은 kind, localPath, repoPath, mode, permission, profiles 순서로 직렬화돼요.

profiles 필드가 없는 항목은 모든 프로필에 적용돼요. 프로필을 나열한 항목은 그중 하나가 활성 프로필일 때만 적용돼요.

상속은 repoPath가 짧은 항목부터 긴 항목 순으로 진행돼요. mode, permission, profiles를 명시하지 않은 항목은 kind가 directory인 가장 가까운 상위 항목에서 그 필드를 가져와요. 각 필드는 서로 독립적으로 상속돼요.

플랫폼 값 객체

localPath, repoPath, mode, permission은 모두 단일 값이 아니라 객체예요. 그래서 manifest 하나로 네 가지 운영체제를 기술할 수 있어요.

{
  "default": "~/.config/tool/config.toml",
  "win": "%APPDATA%/tool/config.toml"
}

default는 필수예요. win, mac, linux, wsl은 선택적 오버라이드이고, 그 순서대로 직렬화돼요.

해석할 때는 플랫폼에 맞는 win, mac, linux를 고르고 없으면 default로 넘어가요. wsl 키는 해석 방식이 달라요. wsl을 먼저 보고, 없으면 linux, 그다음 default를 봐요.

검증 규칙

dotweave는 어떤 명령이 파일을 건드리기 전에 manifest 전체를 검증해요. 아래 규칙에 어긋나면 manifest를 그대로 거부해요.

• repoPath는 .. 세그먼트가 없는 상대 POSIX 경로여야 하고, 비어 있거나 절대 경로면 안 돼요.
• 어떤 경로 세그먼트도 .dotweave.secret이나 .dotweave.symlink로 끝나면 안 돼요. 이 접미사는 artifact 전용이에요.
• 두 항목이 같은 repoPath로 해석되면 안 되고, 같은 localPath로 해석되어도 안 돼요.
• 한쪽이 다른 쪽의 직계 상위인 경우를 빼면 두 localPath가 겹치면 안 돼요. 추적 중인 디렉터리 안에 추적 중인 하위 항목이 있는 건 괜찮지만, 부분적으로만 겹치는 두 항목은 허용되지 않아요.
• 모든 localPath는 홈 디렉터리 안으로 해석되어야 하고, 홈 디렉터리 자체일 수는 없어요.
• 프로필 이름은 ^[A-Za-z0-9][A-Za-z0-9._-]*$에 맞아야 하고, .으로 시작하면 안 되고, .이나 ..일 수 없고, 예약 이름 profiles도 쓸 수 없어요.
• profiles 레지스트리에는 default나 중복 이름이 들어가면 안 돼요.
• 항목이 참조하는 모든 프로필은 등록되어 있거나 default여야 해요.

검증은 보고하기 전에 가능한 모든 실패를 모으기 때문에, 한 번 실행으로 여러 문제를 함께 볼 수 있어요.

예시

{
  "version": 8,
  "repositoryFormat": 1,
  "age": {
    "recipients": ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]
  },
  "profiles": ["work"],
  "entries": [
    {
      "kind": "file",
      "localPath": { "default": "~/.gitconfig" }
    },
    {
      "kind": "directory",
      "localPath": {
        "default": "~/.config/nvim",
        "win": "%LOCALAPPDATA%/nvim"
      },
      "repoPath": { "default": ".config/nvim" }
    },
    {
      "kind": "file",
      "localPath": { "default": "~/.ssh/config" },
      "mode": { "default": "secret" },
      "permission": { "default": "0600" }
    },
    {
      "kind": "file",
      "localPath": { "default": "~/.config/work-vpn.conf" },
      "mode": { "default": "secret" },
      "profiles": ["work"]
    }
  ]
}

오류

JSON 문법 오류, 필드 검사 실패, 읽을 수 없는 파일, 지원하지 않는 버전, 충돌하는 경로는 모두 쓰기 전에 명령을 멈춰요. 정확한 메시지와 해결 방법은 오류 메시지에서 확인하세요.

관련 문서

CLI로 이 필드를 바꾸는 방법은 파일과 디렉터리 추적하기, mode 값이 각각 무엇을 하는지는 동기화 모드에서 확인하세요.