file-singlify(파일 단일 복사본화)
이 스킬의 기능
디스크 / 디렉토리 / 마운트 경로를 스캔하여 여러 번의 복사, 백업, 동기화, 마이그레이션으로 인해 발생한 중복 파일과 중복 디렉토리를 찾아내고, 「단일 복사본화」 계획을 생성합니다: 각 그룹에서 canonical copy 하나를 보존하고, 나머지는 참조 / 삭제 대상 / 링크 제안으로 매핑하며, 절약 가능한 공간을 추정합니다.
핵심 원칙: 기본적으로 읽기 전용이며 dry-run만 수행합니다. 절대로 직접 삭제, 이동, 덮어쓰기, 생성, 하드/소프트 링크를 생성하지 않습니다. 파괴적 작업은 반드시 먼저 보고서를 출력하고 사용자의 명확한 확인을 기다려야 합니다. 스크립트 자체는 항상 읽기 전용입니다. --action-mode는 보고서의 suggested_action 레이블만 변경할 뿐, 어떤 작업도 실행하지 않습니다.
사용 시기
- 사용자가 특정 디스크/디렉토리/여러 폴더를 스캔하여 「완전히 동일한 파일」「중복 디렉토리」「중복 백업」「다중 복사」를 찾고자 할 때
- 사용자가 원본 파일 하나를 보존하고, 참조 매핑, 삭제 제안, 하드/소프트 링크 제안, 중복 제거 보고서, 공간 절약 추정을 원할 때
- 키워드: 중복 제거 / 단일 복사본화 / 중복 디렉토리 병합 / dedup / canonical copy / storage cleanup
적용 불가: 사용자가 파일 내용 분석, 압축, 또는 중복 감지와 관련 없는 정리를 원할 때.
기본 워크플로우
- 경로 및 권한 확인 — 현재 환경이
root_path에 접근 가능한지 확인합니다. 접근 가능하면 스크립트를 실행하고, 접근 불가능하면 사용자에게 디렉토리 목록 / 디렉토리 트리 / 압축 파일 / 접근 가능한 마운트 경로를 요청합니다. 절대 스캔 결과를 허위로 생성하지 않습니다. - 스크립트 실행 (directory-first) — 먼저 디렉토리 일관성으로 중복을 찾고, 그다음 해시로 파일을 확인합니다. 전체 디렉토리가 중복 복사되는 것이 가장 큰 공간 낭비 원인이므로, 디렉토리 수준 결과를 우선 표시합니다.
- 스크립트 출력을 읽고 사용자에게 정리 — 먼저 중복 디렉토리 그룹, 그다음 중복 파일 그룹, canonical 매핑, 절약 공간, 위험 항목 순으로 설명합니다. 스크립트가
uncertain/manual_review로 표시한 항목은 사용자에게 질문하여 명확히 하고, 대신 결정하지 않습니다. - 상위 4개 후속 명령 제공 — 스크립트는 현재 OS/shell에 맞춰 상위 4개 권장 명령(안전 우선: verify → quarantine → hardlink → delete)을 생성합니다. 보고서 섹션 10 / JSON의
recommended_commands를 참조하세요. 이를 사용자에게 제시하고, 사용자의 실제 OS와 shell에 맞게 구문을 조정합니다. 스크립트는 기본적으로 자동 감지하며, 필요한 경우--target-os/--target-shell로 재정의할 수 있습니다. 명령만 제공하고 실행하지 않습니다. 명령에는 대표 샘플 경로가 사용되며, 매핑 테이블에 한 줄씩 적용해야 합니다. - 파괴적 작업 전 재확인 — 사용자가 실제로 삭제하거나 링크를 변경하려 할 때, 먼저 계획을 다시 설명하고 명확한 확인을 요청합니다. 스크립트는 실행하지 않으며, 사용자가 직접 실행하거나 별도로 권한을 부여해야 합니다.
스크립트 실행 시기
환경이 root_path를 직접 읽을 수 있으면 실행합니다. 목록/트리만 얻은 경우, 동일한 판단 로직(디렉토리 구조 일치 → 파일 크기 일치 → 내용 해시 확인)으로 수동 분석하고 「해시 미확인」임을 명확히 밝힙니다.
python3 scripts/scan_file_singlify.py <root_path> \
--scan-mode directory-first \ # 또는 file-only
--hash-algorithm md5 \ # md5 | sha256 | both (엄격하게 both 사용)
--output-format markdown \ # markdown | json | csv
--action-mode report-only \ # report-only|link-plan|delete-plan|hardlink-plan|symlink-plan
--exclude-patterns ".git,node_modules,cache,temp" \
--include-patterns "*.jpg,*.mp4" \
--min-file-size 1024 \
--prefer "/Volumes/Primary" \ # 이 경로를 canonical로 우선 유지
--target-os auto \ # auto|macos|linux|windows (상위 4개 명령 생성용)
--target-shell auto # auto|bash|zsh|fish|powershell|cmd
전체 매개변수 및 판단 세부 사항은 스크립트 --help, references/matching-rules.md 및 references/safety-rules.md를 참조하세요.
출력 형식
스크립트는 구조화된 보고서를 생성하며, 다음을 포함합니다: 스캔 범위, 매개변수, 총 파일/디렉토리/용량, 중복 디렉토리 그룹, 의심되는 중복 디렉토리, 중복 파일 그룹(해시 확인), 절약 가능 공간 추정, canonical 매핑 테이블, 상위 4개 권장 명령(OS/shell별 생성), 위험 및 불확실 항목, 다음 단계 제안. markdown은 사람이 보기 위함이고, json은 프로그램이 소비하기 위함이며(recommended_commands 포함), csv는 중복→canonical 매핑 테이블입니다.
각 매핑 행에는 confidence(confirmed / uncertain)와 suggested_action(keep / delete_duplicate / replace_with_hardlink / replace_with_symlink / create_manifest_reference / manual_review)이 있습니다.
안전 경계
- 기본적으로 절대 파일을 삭제하지 않으며, 자동으로 하드/소프트 링크를 생성하지 않습니다. 스크립트는 읽기 전용입니다.
- 파일 이름 / 크기 / mtime만으로는 동일하다고 판단할 수 없습니다. 후보 선별용일 뿐이며, 최종 결론은 해시 확인(동일 크기 + 동일 해시)이 필수입니다.
- 시스템 디렉토리, 숨김 디렉토리, 애플리케이션 디렉토리, Git 저장소, 데이터베이스, 사진 라이브러리, 클라우드 동기화 디렉토리는 특히 주의해야 합니다.
- 심볼릭 링크는 따르지 않으며, 재귀하지 않습니다. 디렉토리 루프가 발생하면 재귀를 중단하고 보고합니다.
- 권한 부족 / 0바이트 / 특수 파일 / 이미 하드 링크된 파일 → 표시 후 건너뛰고 「건너뜀 / 불확실」 범주에 포함시키며, 확실한 중복으로 처리하지 않습니다.
- canonical을 판단할 수 없으면 후보를 나열하고 사용자 확인을 요청하며, 스스로 결정하지 않습니다.
일반적인 오류
| 오류 | 수정 |
|---|---|
| 경로 접근 가능 여부를 확인하지 않고 「스캔을 가장함」 | 먼저 확인하고, 접근 불가능하면 목록을 요청하며 절대 결과를 허위로 생성하지 않음 |
| 파일 이름/크기/시간만으로 중복이라고 판단 | 후보만 선별하고, 반드시 해시로 확인 |
| 처음부터 모든 파일을 해시 처리 | 먼저 디렉토리 일관성으로 필터링한 후, 후보만 해시 처리 |
| 보고서도 없이 삭제/링크 변경 제안 | 먼저 보고서를 출력하고 명확한 확인을 기다림. 스크립트는 파괴적 작업을 실행하지 않음 |
사용자를 대신해 uncertain 항목 결정 | 불확실 항목을 질문 형태로 사용자에게 다시 던짐 |