xsync

디렉터리 트리 양방향 미러링

xsync는 로컬 파일 시스템과 SharePoint 문서 라이브러리 사이에서 디렉터리 트리 전체를 재귀적으로 미러링합니다. 소스와 대상 두 개의 인자를 받아 둘 중 하나만 SharePoint URL이 되며, URL이 어느 쪽에 붙느냐에 따라 업로드 방향과 다운로드 방향이 결정됩니다.

변경된 파일만 선택 전송

두 번째 실행부터는 새 파일이거나 변경된 파일만 전송하므로, 변경이 없는 경우 추가 전송이 발생하지 않습니다. 1차 비교는 수정 시각(modification time)을 기준으로 하며, SharePoint 측에 업로드한 파일의 수정 시각을 기록하고 다운로드 시에는 로컬 수정 시각을 복원해 양쪽이 일치하도록 유지합니다. 파일 크기는 수정 시각이 달라졌을 때만 차례로 확인합니다.

Word, Excel, PowerPoint 문서의 서버 측 재기록 처리

SharePoint는 Word, Excel, PowerPoint 문서를 저장하면서 라이브러리의 콘텐츠 형식에 묶인 메타데이터를 덧붙이기 때문에, 업로드한 .docx는 서버에서 항상 로컬 파일보다 크게 보입니다. 이런 특성을 고려해 xsync는 항상 수정 시각을 먼저 비교하므로, Office 문서 매번 새 버전이 잘리는 상황을 피합니다.

해시 기반 보조 비교

파일 크기가 같아도 수정 시각이 다른 경우, SharePoint의 QuickXorHash를 로컬에서 계산한 같은 해시와 비교해 실제로 다른 파일만 다시 보냅니다. 따라서 수정 시각만 흔들린 경우에는 불필요한 재전송이 일어나지 않습니다.

대소문자 처리 정책

SharePoint는 이름의 대소문자를 보존하지만 대소문자로 구분하지는 않습니다. 업로드 시에는 대소문자를 무시하고 라이브러리와 비교하기 때문에, 로컬의 d1/ 폴더는 서버의 D1/ 폴더와 같은 폴더로 취급됩니다. 다운로드 시에는 로컬 파일 시스템이 대소문자를 구분하므로 대소문자 비교가 적용됩니다.

선택적 옵션

• `–ignore-times`(`-I`): 수정 시각과 무관하게 모든 파일을 전송합니다. 백업 복원이나 타임스탬프 보존 복사로 인해 내용이 바뀌었지만 수정 시각이 그대로인 경우에 사용합니다.
• `–itemize-changes`(`-i`): 각 줄을 `new`, `time`, `content`, `forced`로 분류해 어떤 이유로 해당 파일이 선택되었는지 보여 줍니다.
• `–dry-run`(`-n`): 실제 변경 없이 전송 계획만 출력합니다.
• `–delete`: 대상에서 더 이상 존재하지 않는 항목을 제거해 소스와 정확히 같은 미러를 만듭니다. 터미널에서 실행할 때는 확인을 먼저 거칩니다.

설치 방법

Windows에서는 winget으로 설치할 수 있습니다.

• `winget install –id Excelano.xsync –exact`

Debian/Ubuntu에서는 Excelano apt 저장소를 추가한 뒤 메타패키지 또는 개별 도구로 설치합니다.

• `sudo sh`로 저장소 설정 스크립트를 한 번 실행
• `sudo apt install xfiles && xcp –install-skill`
• `xsync`만 단독으로 설치할 경우 `sudo apt install xsync`

macOS/Linux의 Homebrew에서는 탭을 등록한 뒤 원하는 도구를 지정해 설치합니다.

• `brew tap excelano/tap`, `brew trust excelano/tap`
• `brew install xftp xcp xsync xfind xtree && xcp –install-skill`

리눅스/macOS용 x86_64 및 arm64 사전 빌드 바이너리도 설치 스크립트로 한 번에 받아 설치할 수 있으며, `XFILES_VERSION`으로 버전을 고정하거나 `XFILES_INSTALL_DIR`로 설치 경로를 지정할 수 있습니다. 소스에서 빌드할 때는 Go 1.24 이상이 필요합니다.

기본 사용법

xsync는 두 개의 인자를 받으며, 둘 중 하나만 SharePoint URL이어야 합니다. URL이 소스에 오면 다운로드, 대상에 오면 업로드 방향이 됩니다.

• 업로드: `xsync ./reports “https://contoso.sharepoint.com/sites/Marketing/Shared Documents/Reports”`
• 다운로드: `xsync “https://contoso.sharepoint.com/sites/Marketing/Shared Documents/Reports” ./reports`

라이브러리 URL은 사이트, 문서 라이브러리, 폴더 모두 가능하며, 브라우저에서 복사한 링크 형태 그대로 사용할 수 있습니다. `?`나 `&`를 포함한 URL은 작은따옴표로 감싸야 셸이 명령을 분리하지 않습니다. 기본 동작은 추가와 갱신만 수행하며 삭제는 하지 않습니다.

활용 예시

• 로컬 보고서 폴더를 SharePoint의 마케팅 사이트 보고서 라이브러리에 주기적으로 업로드 동기화
• SharePoint의 보고서 라이브러리 내용을 로컬 작업 디렉터리로 가져와 로컬 도구로 가공
• `–dry-run –itemize-changes`로 어떤 파일이 전송 대상으로 잡혔는지 미리 확인
• `–dry-run –delete`로 삭제 미러링 적용 전 변경 계획 검토

제한 및 확인 사항

• 수정 시각이 그대로인데 내용만 바뀐 파일은 `–ignore-times`로 명시적으로 재전송을 요청하지 않는 한 변경으로 감지되지 않습니다.
• 기본적으로는 삭제 미러링을 하지 않으므로, 정확한 미러가 필요하면 `–delete`를 함께 지정해야 합니다.
• Word, Excel, PowerPoint 등 Office 문서는 서버에서 메타데이터가 덧붙기 때문에 항상 업로드 후 파일 크기가 커집니다.
• 조직에서 사용자 동의를 제한하는 경우, IT 관리자가 다중 테넌트 앱 등록 ‘Excelano SharePoint tools’에 대한 동의를 미리 승인해야 사용할 수 있습니다.