6. Git 동기화 (Sync)

동기화 (Git Sync)

여러 디바이스에서 같은 메모 묶음을 사용하고 싶다면? Git 동기화를 활성화하세요.
자신의 Git 리포지토리(GitHub / GitLab / cnb 등)를 사용해 동기화하며, 자동으로 commit + pull + push가 진행됩니다.
기술 친화적 사용자에게 더 적합합니다 (Obsidian Git과 같은 사용자층). 일반 사용자용 클라우드 동기화는 준비 중입니다.

6.1 개요

PinSlip의 Git 동기화는 선택적 추가 기능입니다.

• 원리: vault 디렉터리 안에 git 리포지토리를 유지하고, 정기적으로 자동 commit + pull + push를 수행

• 디바운스: 3분 동안 새 작업이 없으면 commit이 트리거됨 (디바운스 — 잠시 기다렸다가 실행)

• 충돌 해결: diff3 3-way 병합 (서로 다른 단락은 자동 병합, 동일 줄 충돌은 표준 마커로 기록)

• 처리 방식: Go 서비스에서 go-git 순수 Go 구현으로 동작하므로, 로컬 git 실행 파일에 의존하지 않음

기본은 꺼져 있으며, 「설정 → Git 동기화」에서 수동으로 활성화해야 합니다.

6.2 연동 절차

준비

1. GitHub / GitLab / cnb 등 플랫폼에서 빈 리포지토리를 새로 만듭니다 (빈 리포지토리를 권장하며, README/license 선택은 권장하지 않음).

2. 쓰기 권한이 있는 Personal Access Token(PAT)을 생성합니다.

   • GitHub: Settings → Developer settings → Personal access tokens → Fine-grained tokens

   • Contents: Read and write 선택

   • token 복사 (한 번만 표시됨)

PinSlip에서 설정

설정 → Git 동기화 → 다음 항목을 입력합니다.

저장 후 PinSlip이 자동으로 로컬 리포지토리를 초기화하고, remote를 설정하며, 첫 commit 및 push를 수행합니다.

자격 증명 저장 위치

• <vault>/.pinslip/git-sync.json에 기록

• <vault>/.pinslip/는 이미 .gitignore에 포함되어 있어, token이 노트와 함께 원격으로 푸시되지 않음

• 설정 화면에서 token 필드를 비워 두면 = 변경하지 않음

6.3 자동 동기화

동기화 사이클

변경 발생 → 3분 동안 새 작업이 없으면 → 자동 commit
  → 가져오기 (fetch + merge)
  → 푸시 (push)

• commit message: sync YYYY-MM-DD HH:mm (n files)

• 정기 push 간격: 기본 10분 (설정에서 1~1440분 사이로 조정 가능)

• 「즉시 동기화」 버튼으로 수동 트리거 가능

• 애플리케이션 종료 전 5초 안에 가능한 한 한 번 push 시도

실패 처리

• 네트워크 / 인증 실패 → 지수 백오프: 1분 → 5분 → 15분

• 상태 패널에 lastError가 표시되어 문제 해결에 도움

동기화 대상

6.4 다중 디바이스 동기화

새 디바이스 연동

1. 새 디바이스에 PinSlip 설치

2. vault 디렉터리 선택 (비어 있어야 함)

3. 설정 → Git 동기화 → 같은 리포지토리 + 같은 Token 입력

4. PinSlip이 자동으로 clone → 인덱스 재구성 → 모든 메모가 표시됨

다중 사용자 협업

PinSlip은 파일을 잠그지 않습니다.

• 여러 사람이 동시에 같은 vault를 편집하면 → 마지막에 쓴 내용이 덮어쓸 위험이 있음

• 브랜치 + PR 방식으로 작업할 것을 권장

동기화 상태

설정 서랍 → Git 동기화 영역에 다음이 표시됩니다.

• 마지막 동기화 시간

• 푸시 대기: n건

• 오류 메시지 (해당되는 경우)

6.5 충돌 해결

이 부분은 Git 동기화에서 가장 중요한 세부 사항 중 하나입니다.

발생 원인

• 두 기기에서 동시에 같은 메모를 수정

• pull 시 깔끔하게 병합할 수 없어 → 마커로 충돌 표시

세 가지 경우

1. 서로 다른 단락의 자동 병합 (가장 흔함)

사용자는 A 단락에 한 줄을 추가
다른 사람이 B 단락을 수정함
​
→ 자동 병합 성공, 사용자에게 방해 없음

2. 동일 줄 충돌 (드묾)

PinSlip은 표준 git conflict markers를 기록합니다.

<<<<<<< HEAD
내가 새로 추가한 줄
=======
다른 사람이 추가한 줄
>>>>>>> origin/main

• 제목 유추는 마커 줄을 건너뛰므로 → 파일명이 마커로 오염되지 않음

• 메인 인터페이스의 메모 목록 상단에 「충돌 대기」 표시가 강조되어 나타남

• API 목록은 conflicted: true를 반환

3. 바이너리 충돌 (이미지)

PinSlip은 양쪽 모두 보존합니다.

• 원격의 원래 이름

• 로컬은 name-conflict-<timestamp>.ext (예: screenshot-conflict-20260731143012.png)

메모에서 충돌 해결

충돌이 있는 메모를 열면 → 전체가 호박색 충돌 배너로 바뀝니다.

• 고정폭 textarea에서 원문 편집 (Markdown 렌더링을 거치지 않음)

• 「모두 로컬 사용」 마커를 한 번에 제거 (로컬 버전 유지)

• 「모두 원격 사용」 마커를 한 번에 제거 (원격 버전 유지)

• 「해결 후 저장」 수동으로 디스크에 기록 (자동 저장을 거치지 않음, 확인 후 저장되도록 보장)

저장 후 마커가 사라지며 → 일반 Markdown 편집기로 자동 전환됩니다.

외부 변경 감지

• 외부 편집기(Obsidian / VS Code)가 디스크의 파일을 수정한 경우 → PinSlip watcher가 감지

• 사용자가 편집 중이 아닐 때 → 자동으로 다시 불러오기 + toast 「동기화됨」

• 사용자가 편집 중일 때 (변경 사항이 있는 경우) → 「최신본 불러오기 / 내 변경 유지」 배너가 표시되어 선택권을 줍니다

이것이 양방향 동기화의 사용성 보장입니다. 두 기기가 서로 변경 사항을 빼앗지 않습니다.

6.6 자주 묻는 문제