AdbFileSync

AdbFileSync는 Android 기기와 로컬 폴더 간의 파일을 ADB(Android Debug Bridge)를 통해 효율적으로 동기화하는 도구입니다. 특히 Obsidian 보관소(Vault)와 같은 파일 구조를 모바일 기기와 동기화하는 데 최적화되어 있습니다.

주요 특징

• 대화형 설정: 기기 선택, 로컬 및 원격 디렉토리 설정을 대화형 CLI를 통해 간편하게 진행할 수 있습니다.
• 스냅샷 기반 삭제 감지: 이전 동기화 상태를 스냅샷으로 저장하여, 양쪽에서 모두 존재하던 파일이 한쪽에서 사라진 경우 이를 삭제로 판단하고 반영합니다.
• 안전한 동기화: 동기화 실행 전 변경 사항(추가, 수정, 삭제)을 미리 보여주고 사용자의 확인을 거칩니다.
• 의존성 최소화: Python 표준 라이브러리만 사용하며, adb 명령어만 있으면 작동합니다.
• 스마트 무시: .obsidian, .trash와 같은 설정 및 휴지통 폴더를 기본적으로 무시합니다.
• .gitignore 지원: local_sync_dir 내의 .gitignore 파일을 인식하며, 서브디렉토리의 규칙도 실제 git과 동일하게 적용하여 파일을 무시합니다.

사전 요구 사항

1. Python 3: 시스템에 Python 3.x가 설치되어 있어야 합니다.
2. 가상환경 및 라이브러리 설정: 본 프로젝트는 .gitignore 패턴 매칭을 위해 pathspec 라이브러리를 사용합니다. 아래 명령어로 가상환경을 설정하고 필요한 패키지를 설치하세요.

   python3 -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   pip install -r requirements.txt

3. ADB (Android Debug Bridge):
   • 시스템 PATH에 adb가 등록되어 있어야 합니다.
   • Android 기기에서 개발자 옵션 및 USB 디버깅이 활성화되어 있어야 합니다.

사용 방법

1. 동기화 실행

기기를 USB로 연결한 후 다음 명령어를 실행합니다:

python3 app.py

• 처음 실행 시: 연결된 기기 목록에서 대상을 선택하고, 원격(기기) 폴더 경로와 로컬 폴더 경로를 입력하는 설정 과정이 진행됩니다.
• 이후 실행 시: 저장된 설정(.adb_device_selection.json)을 바탕으로 즉시 동기화 계획을 생성합니다.

2. 설정 초기화 및 변경

설정된 기기나 디렉토리를 변경하고 싶다면 --initialize 또는 -i 옵션을 사용하세요:

python3 app.py -i

3. 커스텀 설정 파일 사용

기본 설정 파일 위치 대신 특정 파일을 사용하고 싶을 때 사용합니다:

python3 app.py -c my_config.json

설정 및 데이터 파일 형식

AdbFileSync는 작업 디렉토리 또는 지정된 위치에 다음 두 가지 JSON 파일을 생성하여 상태를 관리합니다.

1. 설정 파일 (.adb_device_selection.json)

사용자가 선택한 기기 정보와 동기화할 폴더 경로를 저장합니다.

{
  "selected_device": {
    "serial": "R3CN40AZXYZ",
    "model": "SM-G991N"
  },
  "device_sync_dir": "/sdcard/Documents/Obsidian",
  "local_sync_dir": "/home/user/Obsidian",
  "ignore_git": true
}

• ignore_git: (선택 사항) true로 설정하면 .git 폴더와 그 하위 내용을 동기화 대상에서 제외합니다. 기본값은 false입니다.

2. 스냅샷 파일 ([설정파일명].snapshot)

이전 동기화 시점의 파일 상태(수정 시간, 크기)를 기록하여 삭제 여부를 판단하는 데 사용됩니다. 사용 중인 설정 파일명 뒤에 .snapshot이 붙은 형태로 생성됩니다. (예: .adb_device_selection.json.snapshot)

{
  "version": 1,
  "files": {
    "notes/meeting.md": {
      "local": [1710650000, 1234],
      "device": [1710650010, 1234]
    }
  }
}

• [mtime, size] 형식으로 저장됩니다.

동기화 로직 상세

이 도구는 다음과 같은 규칙으로 동기화를 수행합니다:

1. 신규 파일: 한쪽에만 있는 파일은 반대편으로 복사합니다.
2. 수정된 파일: 수정 시간(mtime)과 파일 크기를 비교하여 더 최신 파일을 반대편에 덮어씁니다.
3. 삭제된 파일:
   • 이전 동기화 스냅샷에 기록되어 있던 파일이 한쪽에서만 사라진 경우, 사용자가 의도적으로 삭제한 것으로 간주하여 반대편 파일도 삭제합니다.
   • 스냅샷 정보가 없는 경우(최초 동기화 등)에는 안전을 위해 삭제를 수행하지 않고 신규 파일로 취급하여 복원합니다.

빌드 및 패키징

PyInstaller를 사용하여 실행 파일(.exe 또는 실행 가능 바이너리)로 만들 수 있습니다:

# packaging.sh 실행 또는 아래 명령어 입력
pyinstaller --onefile --name obsidian_sync app.py

빌드된 실행 파일은 dist/ 디렉토리에 생성됩니다.

프로젝트 구조

• app.py: CLI 진입점 및 대화형 사용자 인터페이스.
• sync.py: 핵심 동기화 알고리즘 및 계획 생성.
• adb_helper.py: ADB 명령어 실행 및 결과 파싱 유틸리티.
• config_store.py: 사용자 설정 저장 및 로드.
• snapshot_store.py: 파일 상태 스냅샷 관리.
• tests/: 단위 테스트 및 통합 테스트 코드.

---

주의: 동기화 과정에서 파일이 덮어쓰여지거나 삭제될 수 있으므로, 중요한 데이터는 반드시 미리 백업해 두시기 바랍니다.