本文中含有需要您注意的重要提示信息，忽略該信息可能對您的業務造成影響，請務必仔細閱讀。
sync命令用于將OSS中的文件同步到本地。
注意事項
要將OSS中的文件同步到本地，您必須具有
oss:GetObject和oss:ListObjects權限。具體操作，請參見為RAM用戶授權自定義的權限策略。
Binary名稱
從ossutil 1.6.16版本開始，命令行中Binary名稱支持直接使用ossutil，您無需根據系統刷新Binary名稱。如果您的ossutil版本低于1.6.16，則需要根據系統刷新Binary名稱。更多信息，請參見命令行工具ossutil命令參考。
文件數量
通過sync命令執行同步任務時，如果沒有攜帶--delete選項，則單次同步任務同步的文件個數無限制。如果攜帶了--delete選項，則單次同步任務最多可同步100萬個文件。當同步的文件個數超出100萬時，將報錯over max sync numbers 1000000.。
sync命令與cp命令的區別
sync命令強制以遞歸的方式遍歷指定文件夾內所有文件或子文件夾。cp命令需增加-r選項才會進行遞歸操作。
通過sync命令將數據同步到OSS時，ossutil支持通過--backup-dir選項指定目標文件夾，用于保存目的端存在而源端不存在的文件。cp命令不支持--backup-dir選項。
sync不支持--version-id選項，無法在已開啟版本控制的Bucket內同步歷史版本文件。cp命令支持--version-id選項。
除以上區別外，sync命令與cp命令用法類似。有關cp命令的用法及示例，請參見cp（下載文件）。
命令格式
ossutil sync cloud_url file_url
[-f --force]
[-u --update]
[--maxdownspeed <value>]
[--delete]
[--backup-dir <value>]
[--enable-symlink-dir]
[--disable-all-symlink]
[--disable-ignore-error]
[--only-current-dir]
[--output-dir <value>]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--range <value>]
[--encoding-type <value>]
[--snapshot-path <value>]
[--include <value>]
[--exclude <value>]
[--disable-crc64]
[--payer <value>]
[-j, --job <value>]
[--parallel <value>]
[--retry-times <value>]參數及選項說明如下：
配置項 | 說明 |
cloud_url | OSS文件夾（目錄）路徑。格式為 |
file_url | 待同步的本地文件夾路徑。例如Linux系統文件夾路徑 |
-f --force | 強制操作，不進行詢問提示。 |
-u，--update | 只有當目標文件不存在，或源文件的最后修改時間晚于目標文件時，ossutil才會執行同步操作。 |
--maxdownspeed | 最大下載速度，單位為KB/s，默認值為0，表示不限制下載速度。 |
--delete | 將目的端指定路徑下的其他文件都刪除，僅保留本次同步的文件。 警告 建議您使用--delete選項前開啟版本控制，防止數據被誤刪。 |
--backup-dir | 指定目標文件夾，用于保存目的端存在而源端不存在的文件。 |
--enable-symlink-dir | 同步鏈接子目錄。 |
--disable-all-symlink | 同步目錄時，忽略所有的鏈接子文件以及鏈接子目錄。 |
--disable-ignore-error | 批量操作時不忽略錯誤。 |
--only-current-dir | 僅同步當前目錄下的文件，忽略子目錄及子目錄下的文件。 |
--output-dir | 指定輸出文件所在的目錄。輸出文件是指批量同步文件出錯時產生的report文件。 如果您不指定輸出文件所在的目錄，則輸出文件默認保存在當前目錄下的ossutil_output目錄。 |
--bigfile-threshold | 設置斷點續傳文件的大小閾值，單位為字節。 默認值：100 MB 取值范圍：0~9223372036854775807 |
--part-size | 設置分片大小，單位為字節。默認情況下ossutil會根據文件大小自行計算合適的分片大小值。 取值范圍：1~9223372036854775807 |
--checkpoint-dir | 指定斷點續傳記錄信息所在的目錄。斷點續傳操作失敗時，ossutil會自動創建名為 |
--range | 下載目標文件的指定字段，并保存為一個新的文件，字段從0開始編號。
|
--encoding-type | 文件名稱的編碼方式。取值為url。如果不指定該選項，則表示文件名稱未經過編碼。 |
--snapshot-path | 指定保存同步文件時的快照信息所在的目錄。在下一次同步文件時，ossutil會讀取指定目錄下的快照信息進行增量同步。 |
--include | 包含符合指定條件的所有文件。 更多信息，請參見include和exclude選項。 |
--exclude | 不包含任何符合指定條件的文件。 更多信息，請參見include和exclude選項。 |
--disable-crc64 | 關閉CRC64數據校驗。 |
--payer | 請求的支付方式。如果希望訪問指定路徑下的資源產生的流量、請求次數等費用由請求者支付，請將此選項的值設置為requester。 |
-j，--job | 多文件操作時的并發任務數，默認值為3，取值范圍為1~10000。 |
--parallel | 單文件操作時的并發任務數，取值范圍為1-10000。 如果不設置此選項，默認由ossutil根據操作類型和文件大小自行決定。 |
--retry-times | 發生錯誤后的重試次數。默認值為10，取值范圍為1~500。 |
使用示例
OSS存儲空間examplebucket下localdir文件夾內有文件a.txt、b.txt以及子文件夾C，本地根目錄下destdir文件夾內有d.txt文件。文件結構如下：
examplebucket 本地根目錄
└── localdir/ └── destdir/
├── a.txt └── d.txt
├── b.txt
└── C/將OSS的localdir文件夾同步到本地
ossutil sync oss://examplebucket/localdir/ destdir/命令執行完畢后，本地destdir文件夾內新增a.txt、b.txt以及子文件夾C。
examplebucket 本地根目錄 └── localdir/ └── destdir/ ├── a.txt ├── a.txt ├── b.txt ├── b.txt └── C/ ├── d.txt └── C/將OSS存儲空間examplebucket下的文件夾localdir同步到本地文件夾destdir，并通過--backup-dir選項指定backup文件夾，用于保存本地指定目錄下已存在而OSS不存在的文件，同時在原有文件夾下的這些文件會被刪除。
ossutil sync oss://examplebucket/localdir/ destdir/ --delete --backup-dir backup/命令執行完畢后，OSS的localdir文件夾將同步到本地，同時本地destdir文件夾內存在的而OSS不存在的文件被轉移到backup文件夾內。即本地destdir文件夾僅保存a.txt、b.txt及子文件夾C，原有的d.txt文件將保存至backup文件夾，且d.txt文件在原有的destdir文件夾下被刪除。
examplebucket 本地根目錄 └── localdir/ ├── destdir/ ├── a.txt │ ├── a.txt ├── b.txt │ ├── b.txt └── C/ │ └── C/ └── backup/ └──d.txt以上示例同步成功后，返回結果中將包含同步的文件數量、文件大小以及完成同步操作所用時長，示例如下：
Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files). average speed 1641000(byte/s)
通用選項
當您需要通過命令行工具ossutil切換至另一個地域的Bucket時，可以通過-e選項指定該Bucket所屬的Endpoint。當您需要通過命令行工具ossutil切換至另一個阿里云賬號下的Bucket時，可以通過-i選項指定該賬號的AccessKey ID，并通過-k選項指定該賬號的AccessKey Secret。
例如，您需要將另一個阿里云賬號下，華東2（上海）地域下存儲空間examplebucket的文件夾srcfolder同步至本地文件夾examplefolder，命令如下：
ossutil sync oss://examplebucket/srcfolder/ examplefolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****關于此命令的其他通用選項的更多信息，請參見通用選項。