sync

Usage notes

Except for the preceding differences, the sync command can be used in the same way as the cp command. For more information about how to use the cp command, see cp.

Synchronize local files to OSS

• Command syntax

  ./ossutil sync file_url cloud_url  [-f] [-u] [--delete] [--backup-dir <value>] [--enable-symlink-dir] [--disable-all-symlink] [--disable-ignore-error] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--snapshot-path=sdir] [--payer requester]

  The preceding command contains the following parameters:
  • file_url: the local path in which the files to synchronize are stored. Examples: /localfolder/ in Linux and D:\localfolder\ in Windows.
  • cloud_url: the path of the OSS folder to which the local files are synchronized. The value of this parameter is in the following format: oss://bucketname/path/. Example: oss://examplebucket/exampledir/. If the value of cloud_url does not end with a forward slash (/), ossutil automatically adds a forward slash to the end of the value.
• Examples
  An OSS bucket named examplebucket contains a folder named example, which contains two objects named a.txt and b.txt and a subfolder named C. In the root folder of the local disk, a folder named example contains a file named d.txt. The following figure shows the structures of the source bucket and the destination local disk.

  examplebucket           root folder of the local disk
  └── example/             └── example/
         ├── a.txt                └── d.txt
         ├── b.txt
         └── C/

  The following examples show how to use the sync command to synchronize local files to OSS in different scenarios:

  • Synchronize the example folder in the local disk to the destination OSS bucket.

    ./ossutil sync example/  oss://examplebucket/example/

    After the command is run, the d.txt file is added to the example folder of the examplebucket bucket as an object named d.txt.

    examplebucket           root folder of the local disk
    └── example/             └── example/
           ├── a.txt                └── d.txt
           ├── b.txt
           ├── d.txt
           └── C/

  • Synchronize the example folder in the local disk to the destination OSS bucket without confirmation.
    When you synchronize a local folder to an OSS bucket, if the OSS bucket contains objects that have the same name as files in the local folder, OSS prompts you to confirm whether you want to overwrite the existing objects. If you confirm that the objects can be overwritten, you can add the -f, --force option in the command to force the overwrite operation. You can run the following command to synchronize the example folder in the local disk to the destination OSS bucket without confirmation:

    ./ossutil sync localfolder/ oss://examplebucket/destfolder/ -f

    After the command is run, the d.txt file is added to the example folder of the examplebucket bucket as an object named d.txt.

    examplebucket           root folder of the local disk
    └── example/             └── example/
           ├── a.txt                └── d.txt
           ├── b.txt
           ├── d.txt
           └── C/

  • Synchronize the example folder in the local disk to the destination OSS bucket and delete all objects in that folder of the examplebucket bucket that do not exist within the same folder in the local disk.
    If the destination of the synchronization is an OSS bucket, you can add the --delete option in the command to delete all objects that do not exist in the source from the destination bucket and retains only the synchronized objects.

    ./ossutil sync example/  oss://examplebucket/example/ --delete

    After the command is run, the example folder in the local disk is synchronized to the examplebucket bucket. The a.txt and b.txt objects and the subfolder C within the example folder of the examplebucket bucket are deleted. Only the synchronized d.txt file is retained in the example folder of the examplebucket bucket.

    examplebucket           root folder of the local disk
    └── example/             └── example/
           └── d.txt                └── d.txt

Synchronize OSS objects to local disks

• Command syntax

  ./ossutil sync cloud_url file_url  [-f] [-u] [--delete] [--backup-dir] [--only-current-dir] [--disable-ignore-error] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--range=x-y] [--payer requester]

  You can run the preceding sync command to synchronize objects stored in a bucket to local disks. The command contains the following parameters:
  • file_url: The local path to which OSS objects are synchronized. Examples: /localfolder/ in Linux and D:\localfolder\ in Windows.
  • cloud_url: The path of the OSS folder in which the objects to synchronize are stored. The value of this parameter is in the following format: oss://bucketname/path/. Example: oss://examplebucket/exampledir/.
• Examples
  The source OSS bucket named examplebucket contains a folder named example, which contains two objects named a.txt and b.txt and a subfolder named C. In the root folder of the destination local disk, a folder named example contains a file named d.txt. The following figure shows the structures of the source bucket and the destination local disk.

  examplebucket           root folder of the local disk
  └── example/             └── example/
         ├── a.txt                └── d.txt
         ├── b.txt
         └── C/

  The following examples show how to use the sync command to synchronize OSS objects to local disks in different scenarios:

  • Synchronize the example folder of the examplebucket bucket to the local folder.

    ./ossutil sync  oss://examplebucket/example/  example/ 

    After the command is run, the a.txt and b.txt files and the subfolder C are added to the example folder in the local disk.

    examplebucket           root folder of the local disk
    └── example/             └── example/
           ├── a.txt                ├── a.txt 
           ├── b.txt                ├── b.txt
           └── C/                   ├── d.txt
                                       └── C/ 

  • Synchronize the example folder of the examplebucket bucket to the local folder, and migrate files that do not exist in example folder of the examplebucket bucket but do exist in the destination local folder to the backup folder of the examplebucket bucket.

    ./ossutil sync oss://examplebucket/example/  example/  --delete  --backup-dir backup/

    After the command is run, the example folder of the examplebucket bucket is synchronized to the local disk, and the files in the example folder in the local disk are migrated to the backup folder of the examplebucket bucket. In this example, the a.txt and b.txt files and the subfolder C synchronized from OSS are retained in the example folder in the local disk. The d.txt file is added to the backup folder of the examplebucket bucket.

    examplebucket           root folder of the local disk
    └── example/             ├── example/
           ├── a.txt         │     ├── a.txt 
           ├── b.txt         │     ├── b.txt
           └── C/            │     └── C/                             
                                └── backup/
                                       └──d.txt

Synchronize objects between OSS buckets

• Command syntax

  ./ossutil sync cloud_url cloud_url [-f] [-u] [--delete] [--backup-dir] [--only-current-dir] [--disable-ignore-error] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--payer requester]

  You can use the preceding sync command to synchronize data between OSS buckets. The source bucket and the destination bucket must be in the same region. The cloud_url parameter in the command indicates the paths of the source bucket and destination bucket. The value of this parameter is in the following format: oss://bucketname/path/. Example: oss://examplebucket/exampledir/.
• Examples
  Your Alibaba Cloud account owns two buckets named examplebucket1 and examplebucket2. The examplebucket1 bucket contains the example and test folders. The examplebucket2 bucket contains the example folder. The following figure shows the structures of examplebucket1 and examplebucket2.

  examplebucket1          examplebucket2
  ├── example/            └── example/
  │      ├── a.txt               ├── a.txt
  │      └── b.txt               └── c.txt
  └── test/     
          └── d.txt       

  The following examples show how to use the sync command to synchronize data between two OSS buckets in different scenarios:

  • Synchronize the example folder of the examplebucket1 bucket to the test folder of the same bucket.

    ./ossutil sync oss://examplebucket1/example/  oss://examplebucket1/test/

    After the command is run, all objects in the example folder are synchronized to the test folder.

    examplebucket1          examplebucket2
    ├── example/            └── example/
    │      ├── a.txt               ├── a.txt
    │      └── b.txt               └── c.txt
    └── test/        
            ├── a.txt
            ├── b.txt
            └── d.txt      

  • Synchronize the example folder of the examplebucket1 bucket to the example folder of the examplebucket2 bucket.

    ./ossutil sync oss://examplebucket1/example/ oss://examplebucket2/example/

    After the command is run, all objects in the example folder of the exmplebucket1 bucket are synchronized to the example folder of the examplebucket2 bucket.

    examplebucket1          examplebucket2
    ├── example/            └── example/
    │      ├── a.txt               ├── a.txt  
    │      └── b.txt               ├── b.txt
    └── test/                       └── c.txt 
            └── d.txt

  • Synchronize all objects in examplebucket1 to examplebucket2, and delete objects that do not exist in examplebucket1 from examplebucket2.

    ./ossutil sync oss://examplebucket1 oss://examplebucket2 --delete

    After the command is run, the example and test folders of the examplebucket1 bucket are synchronized to the root folder of the examplebucket2 bucket. Other objects in the examplebucket2 bucket are deleted.

    examplebucket1          examplebucket2
    ├── example/            ├── example/
    │      ├── a.txt       │      ├── a.txt  
    │      └── b.txt       │      └── b.txt
    └── test/               └── test/  
            └── d.txt               └── d.txt                  

Common options