From dca1def87cf40f78276d41ff77b94e296ad4874d Mon Sep 17 00:00:00 2001 From: altair823 Date: Sun, 10 May 2026 23:41:56 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=EB=8F=99=EA=B8=B0=ED=99=94=20?= =?UTF-8?q?=EC=84=B9=EC=85=98=20Cut=20E=20=EB=B0=98=EC=98=81=20=E2=80=94?= =?UTF-8?q?=20=EC=96=91=EB=B0=A9=ED=96=A5=20sync=20+=20ConflictModal=20+?= =?UTF-8?q?=20Silent=20risk=20+=20Troubleshoot?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 59 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 349120b..7f69d95 100644 --- a/README.md +++ b/README.md @@ -190,37 +190,58 @@ inkling.md 원본 제품 브리프 v1.4 --- -## 원격 백업 (선택, F6-L2) +## 동기화 (Git, F21 Cut E) -Inkling 데이터를 사적 git 원격에 백업하려면 한 번만 설정하면 된다. 인코딩된 형식이 아니라 평문 마크다운(F5 export 형식)으로 저장되니, **반드시 비공개 repo** 를 사용한다. +Inkling 데이터를 사적 git 원격으로 양방향 동기화 (Mac ↔ Windows 등). 평문 마크다운(F5 export 형식)으로 저장되니 **반드시 비공개 repo** 를 사용한다. + +상세 도움말은 앱 내 설정 → 동기화 저장소 → "도움말" 버튼 (4 섹션 modal) 참조. 본 섹션은 setup + 주요 시나리오 요약. ### 일회 설정 -```bash -# 1. 빈 사적 repo 생성 (예: gitea, GitHub private) +1. 빈 사적 repo 생성 (Gitea / GitHub private) +2. 앱 → 설정 → 동기화 저장소 → URL 입력 → "저장" +3. "연결 테스트" 클릭해 인증 / 네트워크 확인 +4. 자동 sync 사용 토글 + interval (기본 30분) 확인 -# 2. 데이터 디렉터리에 git 초기화 + 원격 등록 -cd "%APPDATA%\Inkling\Inkling\profiles\default\sync" # Windows -git init -git remote add origin https://your-host/owner/inkling-data.git -git fetch origin || true # 빈 repo 면 무시 +URL 형식 (둘 중 하나): -# 3. 자격증명 설정 (Windows Credential Manager 자동 / 또는 token 임베드 URL) +- SSH: `git@host:user/repo.git` +- HTTPS: `https://host/user/repo.git` -# 4. 첫 동기화: 트레이 → "지금 동기화" -``` +`git@https://...` 같은 혼합 형식은 거부된다. -처음 sync 시 SyncService 가 `/sync/` 안에 F5 export 트리(notes/, media/, index.jsonl, manifest.json)를 덮어쓰고 `git add -A && git commit && git push -u origin ` 를 자동 수행. +### 일상 사용 -### 사용 +- 자동 sync: 설정한 interval 마다 + 앱 종료 시 1회 +- 수동 sync: 트레이 → "지금 동기화" +- 충돌 발생 시 트레이 토스트 + 설정 페이지의 "충돌 해결…" 버튼 → ConflictModal -- 트레이 → "지금 동기화" 로 수동 트리거 -- 앱 종료 시 자동 1회 (sync dir 이 설정된 경우만) -- 변경 없으면 토스트 "변경 사항 없음", 변경 있으면 "동기화 완료" +### 충돌 해결 (ConflictModal) -설정이 안 됐으면 트레이 토스트로 안내. 한 번 설정하면 이후 push 는 OS credential helper 가 자동 처리. +같은 노트를 두 기기에서 동시에 수정하면 path 별 결정 (내 것 / 원격) 을 받는다. -데이터 라이프사이클 측면에서 F6-L1 (로컬 스냅샷, 자동) + F5/F6-L3 (수동 export/import) + F6-L2 (원격 git, 반자동) 3-layer 구조의 마지막 layer. +- **내 것 사용**: 이 기기의 변경을 보존, 원격 변경을 폐기 +- **원격 사용**: 원격 변경을 가져오고, 이 기기의 변경을 폐기 + +3 케이스: + +1. 편집/편집 — 양 텍스트 비교 후 더 새롭고 완전한 쪽 선택. 둘 다 보존하려면 한쪽 선택 + 사후 수동 병합 ('both' 미지원) +2. 삭제/편집 — 삭제가 의도였으면 원격 사용 (trash 측), 수정이 더 중요하면 내 것 사용 (편집 측 = trash 취소) +3. AI 결과 충돌 — 한쪽 선택 후 AI 재실행 권장 + +### Silent risk + +- **시계 어긋남 (NTP)**: 양 기기 시계가 다르면 timestamp merge 가 잘못된 결과를 낼 수 있음. NTP 동기화 끄지 말 것 +- **두 기기 동시 수정 회피**: 같은 노트를 동시에 수정하면 conflict 가 잦아짐 +- **자동 sync 실패 silent**: 주기적 sync 실패 시 토스트 안 뜸. 마지막 sync 시각 / 결과는 설정 페이지에서 확인 + +### Troubleshoot + +- **"연결 테스트" 실패** — 네트워크 (브라우저로 호스트 접속) / 인증 (SSH key 또는 token) / URL 오타 점검 +- **인증 실패 (push 안 됨)** — SSH 는 public key 등록 점검, HTTPS 는 OS credential helper (Windows Credential Manager / macOS Keychain) 의 저장 token 점검 +- **URL 변경** — 설정 페이지에서 새 URL 입력 → 저장 (`git remote set-url origin` 자동 처리) + +데이터 라이프사이클: F6-L1 (로컬 스냅샷, 자동) + F5/F6-L3 (수동 export/import) + F21 Cut E (양방향 git sync) 3-layer 구조. ---