Git 동기화

사용 중단됨

Git 동기화는 현재 버전에서 사용 중단되었으며 더 이상 외부에서 사용할 수 없습니다. 플러그인은 WebDAV Durable Bundle 동기화로 전환되었습니다. 이는 WebDAV 프로토콜을 사용하여 Synthesis 영속 상태 스냅샷(Git 저장소 대신)을 교환하여 더 가벼운 크로스 디바이스 동기화를 제공합니다.

대신 WebDAV 동기화를 사용하세요.

Git 동기화는 암시적 내부 전송 채널로만 유지됩니다(과거 진단 및 향후 정리에 사용됨). 아래 문서는 역사적 참고를 위해 보관되어 있습니다.

Git 동기화는 Synthesis Workbench의 선택적 기능으로, Canonical Store의 지식 그래프 데이터를 Git 저장소로 동기화하여 버전 제어, 백업 및 협업을 가능하게 합니다.

사용 사례

버전 제어: 모든 태그 어휘, 토픽 통합 및 개념 지식 베이스의 변경 이력 추적
백업: 구조화된 지식 데이터를 원격 Git 저장소로 백업
협업: 여러 연구자가 동일한 태그 시스템과 분석 결과를 공유

구성

Zotero 환경설정에서 Git 동기화를 구성합니다:

Zotero → 설정 → Zotero Agents → Synthesis Git Sync

설정	설명
Git 동기화 활성화	동기화 켜기/끄기
원격 저장소 URL	Git 원격 저장소 주소 (HTTPS 및 SSH 지원)
브랜치 이름	동기화에 사용되는 Git 브랜치

사전 요구 사항

Git 설치됨 (시스템 PATH에서 사용 가능)
접근 가능한 Git 원격 저장소 (GitHub, Gitee, 자체 호스팅 등)
HTTPS 저장소를 사용하는 경우, Git 자격 증명이 구성되어 있어야 함

동기화 범위

Git 동기화는 표준 도메인 자산(Canonical Store의 구조화된 지식 데이터)만 동기화하며, 런타임 데이터는 제외합니다.

동기화되는 항목

도메인	내용
`tags/`	제어된 태그 어휘
`topics/`	토픽 통합을 위한 구조화된 아티팩트
`concepts/`	개념 지식 베이스 (개념, 의미, 별칭, 관계)
`topic-graph/`	토픽 그래프 노드 및 엣지
`citation-graph/`	인용 그래프 스냅샷

동기화되지 않는 항목

동기화되지 않음	이유
`state/` 데이터베이스	SQLite 런타임 상태; 표준 자산에서 재구축 가능
런타임 로그	임시 진단 데이터
작업 공간 파일	실행 중에 생성된 임시 데이터
큐 및 잠금 상태	내부 스케줄링 상태

동기화 상태 머신

동기화 시스템은 일관성을 보장하기 위해 큐 기반 상태 머신을 사용합니다:

idle → queued → syncing → idle
                  ↓
            blocked_conflict
                  ↓
            failed_retryable / failed_permanent / disabled

상태	설명
`idle`	유휴 상태, 대기 중인 작업 없음
`queued`	동기화 대기 중인 변경 사항
`syncing`	동기화 작업 진행 중
`blocked_conflict`	동기화 실패; 충돌 수동 해결 필요
`failed_retryable`	임시 실패 (예: 네트워크 문제); 재시도 가능
`failed_permanent`	영구적 실패 (예: 구성 오류)
`disabled`	Git 동기화가 꺼져 있음

충돌 처리

로컬과 원격 모두에 병합되지 않은 변경 사항이 있을 때 충돌이 발생합니다.

충돌 보고서

충돌 보고서에는 다음이 나열됩니다:

충돌하는 파일 경로
로컬 버전 해시
원격 버전 해시
충돌 이유 (예: 양쪽에서 동시에 동일한 태그를 수정)

해결 단계

홈 페이지의 Git 동기화 패널에서 충돌 보고서 확인
충돌 내용 분석 (파일 수준 세분성)
로컬 버전을 유지할지, 원격 버전을 유지할지, 또는 수동으로 병합할지 결정
병합을 완료한 후 변경 사항을 커밋

모범 사례

정기적 동기화

Git 동기화는 실시간 동기화가 아닙니다. 다음을 권장합니다:

일괄 태그 관리 또는 토픽 수정 완료 후 수동으로 동기화 트리거
또는 홈 페이지에서 동기화 상태를 모니터링하여 큐가 밀리지 않도록 관리

팀 협업

여러 사람이 동일한 태그 어휘를 공유할 때:

어휘 관리를 위한 전담 담당자를 지정하는 것을 권장
Git 동기화를 통해 태그 변경이 전파된 후, 다른 멤버가 동기화 pull 수행
협의를 통해 충돌 해결

백업 전략

Git 동기화는 Canonical Store를 보완하는 추가 백업으로, Zotero 데이터 자체의 백업을 대체하지 않음
Git 저장소를 원격으로 정기적으로 push하는 것을 권장 (내장 지원)
초기 동기화는 시간이 오래 걸릴 수 있음; 이후 동기화는 증분 방식

다음 단계

홈 대시보드 — 동기화 상태 패널 확인
태그 관리 — 제어된 태그 어휘 관리
환경설정 — Git 저장소 파라미터 구성

사용 사례​

구성​

사전 요구 사항​

동기화 범위​

동기화되는 항목​

동기화되지 않는 항목​

동기화 상태 머신​

충돌 처리​

충돌 보고서​

해결 단계​

모범 사례​

정기적 동기화​

팀 협업​

백업 전략​

다음 단계​