Help Center/ Object Storage Service/ Tools Guide/ obsutil/ Object Commands/ Uploading and Deleting Objects in Incremental Synchronization
Updated on 2026-09-20 GMT+08:00
View PDF
Share

Uploading and Deleting Objects in Incremental Synchronization

Function

In addition to uploading incremental objects, this command deletes objects that do not exist in the local source path from the target OBS bucket, ensuring that the content in the local source path is the same as that in the target OBS bucket. Incremental synchronization deletion has the following three meanings:

  1. "Incremental" means that the local source files are compared with their counterparts in the target bucket and only those with content changes are uploaded.
  2. "Synchronization" means that after the command is executed, all source files in the local path have their counterparts in the target OBS bucket.
  3. "Deletion" means that after the command is executed, objects that do not have their corresponding files in the local source path will be deleted from the target OBS bucket.
  • Do not change the local file or folder during synchronization. Otherwise, the synchronization may fail or data may be inconsistent.
  • During synchronous upload, each file is compared with the object at the corresponding path in the bucket. A file is uploaded only when the object does not exist, the object size differs from the file size, or the object was last modified earlier than the file.
  • Using the -delete parameter will delete objects from the OBS bucket. Object deletion cannot be undone. Exercise caution when using this parameter. Before deleting objects, you are advised to use the -dryRun parameter to conduct a dry run and check whether the list of objects to be deleted meets the expectation.
  • If the source path is an empty directory, the command will be rejected and an error will be reported to prevent all objects in the bucket from being deleted by mistake.
  • If versioning is not enabled for the target bucket, deleted objects cannot be restored. You are advised to enable versioning for the bucket to prevent accidental data deletion.
  • If you do not use key to specify the target object name prefix, the command will scan the entire bucket and may delete all objects that do not have their corresponding files in the local source path. Exercise caution when doing so.
  • When the -delete parameter is used, the command will ask for confirmation before deleting objects. To skip the confirmation, use the -delete parameter together with the -f parameter.

When you compare each local file with data in the bucket, a billable HEAD request is generated. For details, see Requests. When the system scans for objects to be deleted in the target bucket, a billable LIST request is generated.

Command Line Structure

  • sync command

    The sync command provides the incremental synchronization capability. You can directly use the -delete parameter.

    • Windows 
      obsutil sync folder_url obs://bucket[/key] [-delete] [-f] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • macOS or Linux 
      ./obsutil sync folder_url obs://bucket[/key] [-delete] [-f] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • cp command

    To run the cp command, you must also use the -u, -r, and -delete parameters.

    • Windows 
      obsutil cp folder_url obs://bucket[/key] -r -u [-delete] [-f] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • macOS or Linux 
      ./obsutil cp folder_url obs://bucket[/key] -r -u [-delete] [-f] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • When using the -delete parameter in the cp command, you must also specify the -u (incremental) and -r (recursive folder) parameters. Otherwise, an error will be reported.
  • The sync command provides the incremental synchronization capability. You do not need to specify the -u and -r parameters.
  • The -delete parameter can only be used for upload (from local to OBS), but cannot be used for download or replication.

Examples

Assume that the content of a local folder is as follows:

└── src1     
      ├── src2
            ├── test1.txt         
            └── test2.txt     
      └── test3.txt

Assume that bucket bucket-test contains the following objects:

obs://bucket-test/src1/
obs://bucket-test/src1/src2/
obs://bucket-test/src1/src2/test1.txt
obs://bucket-test/src1/src2/old.txt
obs://bucket-test/src1/legacy.txt
  • In Linux, run ./obsutil sync /src1 obs://bucket-test/src1 -delete to perform incremental synchronization upload and delete redundant objects from the bucket.

    The execution process is as follows:

    1. The system incrementally uploads the changed local files (test2.txt and test3.txt).
    2. The system scans the objects in the bucket and finds the objects (old.txt and legacy.txt) that do not have corresponding files on the local host.
    3. The system prompts for confirmation before deletion. After you enter y, the system deletes old.txt and legacy.txt.
    ./obsutil sync /src1 obs://bucket-test/src1 -delete

Start at 2024-09-25 04:48:10.1147483 +0000 UTC

Parallel:      5                   Jobs:          5
Threshold:     50.00MB             PartSize:      auto
VerifyLength:  false               VerifyMd5:     false
CheckpointDir: /root/.obsutil_checkpoint

Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed
OutputDir: /root/.obsutil_output

[========================================================] 100.00% tps:35.71 2.02 KB/s 7.20MB/7.20MB 0s
Succeed count:   5         Failed count:    0 
Succeed bytes:     xxxx 
Metrics [max cost:90 ms, min cost:45 ms, average cost:63.80 ms, average tps:35.71, transferred size: 7.20MB] 

[Pre-scan] Local file count: 3
[Pre-scan] Scanning OBS objects under obs://bucket-test/src1/ ... 
[Pre-scan] OBS objects scanned: 4, objects to delete: 2 Found 2 objects to delete in obs://bucket-test/src1/ 
Full list saved to: /root/.obsutil_output/sync_delete_target_files_20240925_104810_104786c8.txt
Please input (y/n) to confirm: y 
[Step 5/6] Deleting 2 objects from obs://bucket-test/src1/ ... 
[Step 6/6] Delete completed: succeed 2, failed 0 

Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed
  • In Linux, run ./obsutil sync /src1 obs://bucket-test/src1 -delete -f to perform the deletion without confirmation. 
    ./obsutil sync /src1 obs://bucket-test/src1 -delete -f

    If the -f parameter is used, the deletion is performed without a confirmation prompt. This parameter is applicable to script automation scenarios.

  • In Linux, run ./obsutil sync /src1 obs://bucket-test/src1 -delete -dryRun to conduct a dry run. 
    ./obsutil sync /src1 obs://bucket-test/src1 -delete -dryRun

    Only the list of files to be uploaded and deleted is displayed, and the upload and deletion operations are not performed. You are advised to use the -dryRun parameter to confirm the result when using the -delete parameter for the first time.

  • In Windows, run obsutil cp d:\temp obs://bucket-test/temp -r -u -delete to perform incremental synchronization upload and deletion. 
    obsutil cp d:\temp obs://bucket-test/temp -r -u -delete

    When using the -delete parameter in the cp command, you must also specify the -r and -u parameters. Otherwise, an error will be reported.

Parameter Description

The following table lists only the parameters related to incremental synchronization deletion. For details about other parameters, see Synchronously Uploading Incremental Objects.

Parameter

Optional or Mandatory

Description

delete

Optional (additional parameter)

During incremental synchronization upload, objects that do not have corresponding files in the local source path are deleted from the target OBS bucket. This parameter can only be used for upload (from local to OBS). When this parameter is used in the cp command, the -u and -r parameters must be specified. When this parameter is used in the sync command, no additional parameters are required.

f

Optional when -delete is used (additional parameter)

This parameter skips the confirmation message for the -delete operation. If this parameter is not used, the system prompts you to confirm the deletion. If this parameter is used, the deletion is performed directly without any confirmation.

dryRun

Optional (additional parameter)

The dry run mode. In this mode, the actual upload and deletion operations are not performed, and only the list of files to be operated is displayed. You are advised to use this parameter to confirm the result when using the -delete parameter for the first time.

FAQ

  • Error "source is empty, --delete is not allowed" is reported when the -delete parameter is used.

    If the source path is an empty directory, the command will be rejected. This is to prevent all objects in the bucket from being deleted by mistake. In this case, check whether the source path is correct and ensure that the source directory contains the files to be uploaded.

  • Error "no files matched for upload, --delete is not allowed" is reported when the -delete parameter is used.

    All files in the source path are excluded by the filter criteria (such as -include, -exclude, and -timeRange). As a result, there are no files to be uploaded. The deletion operation is not allowed to prevent objects from being deleted by mistake. In this case, check whether the filter criteria are too strict.

  • Error "--delete is only supported in upload mode" is reported when the -delete parameter is used.

    The -delete parameter can only be used for upload (from local to OBS) but cannot be used for download or cross-bucket replication. Ensure that the source path in the command is a local path and the target path is an OBS bucket path.

  • Error "--delete must be used together with -u (--update)" is reported when the cp command is executed.

    When using the -delete parameter in the cp command, you must also use the -u (--update) parameter to enable the incremental mode.

  • Error "--delete must be used together with -r to upload folder" is reported when the cp command is executed.

    When using the -delete parameter in the cp command, you must also use the -r parameter to specify folder upload.

  • A warning is displayed when versioning is not enabled for the bucket.

    Objects deleted from a bucket with versioning disabled cannot be restored. You are advised to enable versioning for the bucket to prevent accidental data deletion.

Response

Refer to Response for uploading an object.

Compared with common incremental synchronization upload, incremental synchronization upload using the -delete parameter will display deletion statistics additionally in the response results.

Delete succeed:    2         Delete failed:    0
Parent topic: Object Commands