The ls command is used to list buckets, objects, or parts.
Note The commands described in this topic apply to Linux. To use the commands in other
systems, replace ./ossutil in the command with the actual executable program name.
For example, you can use the help command in 32-bit Windows systems by running ossutil32.exe help.
Command syntax
./ossutil ls [oss://bucket[/prefix]] [-s] [-d] [-m] [--limited-num num] [--marker marker] [--upload-id-marker umarker] [--payer requester] [--include include-pattern] [--exclude exclude-pattern] [--version-id-marker id_marker] [--all-versions] [-c file]
Examples
- List buckets
./ossutil ls CreationTime Region StorageClass BucketName 2016-10-2116:18:37 +0800 CST oss-cn-hangzhou Archive oss://bucket1 2016-12-0115:06:21 +0800 CST oss-cn-hangzhou Standard oss://bucket2 2016-07-2010:36:24 +0800 CST oss-cn-hangzhou IA oss://bucket3 Bucket Number is:3 0.252174(s) elapsed
Note You can also use the./ossutil ls oss://
command to list buckets. - List buckets by page
./ossutil ls oss:// --limited-num=${num} --marker=${bucketname}
When the number of buckets is large, you can use the--limited-num
and--marker
options to list buckets by page.--limited-num
is used to control the number of entries displayed on each page.--marker
specifies the bucket from which you want to start listing. The results displayed by ossutil are returned starting from the first bucket in alphabetical order after the value of the marker. In most cases, this parameter value is set to the last bucket name displayed on the previous page.
The following code provides an example on how to list the first two buckets by page:./ossutil ls oss:// --limited-num=1 -s oss://bucket1 Bucket Number is:1 0.303869(s) elapsed ./ossutil ls oss:// --limited-num=1 -s --marker=bucket1 oss://bucket2 Bucket Number is:1 0.257636(s) elapsed
- List all objects in a specified bucket
./ossutil ls oss://bucket1 LastModifiedTime Size(B) StorageClass ETAG ObjectName 2016-12-0115:06:37 +0800 CST 10363812 Standard 61DE142E5AFF9A6748707D4A77BFBCFB oss://bucket1/a1 2016-12-0115:06:42 +0800 CST 10363812 Standard 61DE142E5AFF9A6748707D4A77BFBCFB oss://bucket1/a2 2016-12-0115:06:45 +0800 CST 10363812 Standard 61DE142E5AFF9A6748707D4A77BFBCFB oss://bucket1/a3 Object Number is:3 0.007379(s) elapsed
- List all objects by page
./ossutil ls oss://bucket --limited-num=${num} --marker=${obj}
Similar to the operation of listing buckets by page, you can use the--limited-num
and--marker
options to list objects by page. The following code provides an example of how to list the first two objects in the bucket1 root directory:./ossutil ls oss://bucket1 --limited-num=1 LastModifiedTime Size(B) StorageClass ETAG ObjectName 2016-12-0115:06:37 +0800 CST 10363812 Standard 61DE142E5AFF9A6748707D4A77BFBCFB oss://bucket1/a1 Object Number is:1 0.007379(s) elapsed $./ossutil ls oss://bucket1 --limited-num=1 --marker=a1 LastModifiedTime Size(B) StorageClass ETAG ObjectName 2016-12-0115:06:42 +0800 CST 11673 Standard D41D8CD98F00B204E9800998ECF8427E oss://bucket1/a2 Object Number is:1 0.008392(s) elapsed
- List UploadIDs.
You can add the
-m
option to the ls command to list upload IDs of all incomplete multipart upload tasks initiated to objects with a specified prefix../ossutil ls oss://bucket1/obj1 -m InitiatedTime UploadID ObjectName 2017-01-13 03:45:26 +0000 CST 15754AF7980C4DFB8193F190837520BB oss://bucket1/obj1 2017-01-13 03:43:13 +0000 CST 2A1F9B4A95E341BD9285CC42BB950EE0 oss://bucket1/obj1 UploadId Number is: 2 0.070070(s) elapsed
- List all objects and incomplete multipart upload tasks
You can add the
-a
option to the ls command to list the upload IDs of all incomplete multipart upload tasks initiated to objects with a specified prefix and the uploaded objects with the prefix../ossutil ls oss://bucket1 -a LastModifiedTime Size(B) StorageClass ETAG ObjectName 2015-06-0514:06:29 +0000 CST 201933 Standard 7E2F4A7F1AC9D2F0996E8332D5EA5B41 oss://bucket1/dir1/obj11 2015-06-0514:36:21 +0000 CST 201933 Standard 6185CA2E8EB8510A61B3A845EAFE4174 oss://bucket1/obj1 2016-04-0814:50:47 +0000 CST 6476984 Standard 4F16FDAE7AC404CEC8B727FCC67779D6 oss://bucket1/sample.txt Object Number is:3 InitiatedTime UploadID ObjectName 2017-01-1303:45:26 +0000 CST 15754AF7980C4DFB8193F190837520BB oss://bucket1/obj1 2017-01-1303:43:13 +0000 CST 2A1F9B4A95E341BD9285CC42BB950EE0 oss://bucket1/obj1 2017-01-1303:45:25 +0000 CST 3998971ACAF94AD9AC48EAC1988BE863 oss://bucket1/obj2 2017-01-2011:16:21 +0800 CST A20157A7B2FEC4670626DAE0F4C0073C oss://bucket1/tobj UploadId Number is:4 0.191289(s) elapsed
- Display the listed results in short format
./ossutil ls oss://bucket1 -s oss://bucket1/a1 oss://bucket1/a2 oss://bucket1/a3 Object Number is:3 0.007379(s) elapsed
- List buckets in the form of directories
You can use the
-d
option to list objects and subdirectories in the current directory, rather than recursively displaying all objects in all subdirectories. Example:./ossutil ls oss://bucket1 -s -d oss://bucket1/obj1 oss://bucket1/sample.txt oss://bucket1/dir1/ Object and Directory Number is:3 0.119884(s) elapsed
- List objects or subdirectories with a specific prefix in the current directory
./ossutil ls oss://bucket1/test -d oss://bucket1/test.jpg oss://bucket1/test/ Object and Directory Number is: 2
- List buckets in pay-by-requester mode
./ossutil ls oss://bucket --payer=requester
- List all versions of all objects in a versioning-enabled bucket
./ossutil ls oss://bucket1 --all-versions LastModifiedTime Size(B) StorageClass ETAG VERSIONID IS-LATEST DELETE-MARKER ObjectName 2019-06-11 10:54:51 +0800 CST 0 CAEQARiBgICUsOuR2hYiIDI3NWVjNmEyYmM0NTRkZWNiMTkxY2VjMDMwZjFlMDA3 true true oss://bucket1/test1.jpg 2019-06-11 11:03:37 +0800 CST 0 CAEQARiBgIDZtvuR2hYiIDNhYjRkN2M5NTA5OTRlN2Q4YTYzODQwMzQ4NDYwZDdm true true oss://bucket1/test.jpg 2019-06-11 10:53:46 +0800 CST 118076 Standard FFDB300F053AAF06F4C4C58A4869C427 CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk false false oss://bucket1/test1.jpg 2019-06-11 11:02:05 +0800 CST 345374 Standard 078A9852BCF81DC4811E6EDCBFD121BE CAEQARiBgICNz_iR2hYiIGJjZTBjNDQxYWRhNTQ2ZTNiNmMzYzQ1YzMzMDA5ZjUw false false oss://bucket1/test.jpg Object Number is: 4 0.692000(s) elapsed
- List all versions of a specific object in a versioning-enabled bucket
./ossutil ls oss://bucket1/test.jpg --all-versions LastModifiedTime Size(B) StorageClass ETAG VERSIONID IS-LATEST DELETE-MARKER ObjectName 2019-06-11 11:03:37 +0800 CST 0 CAEQARiBgIDZtvuR2hYiIDNhYjRkN2M5NTA5OTRlN2Q4YTYzODQwMzQ4NDYwZDdm true true oss://bucket1/test.jpg 2019-06-11 11:02:05 +0800 CST 345374 Standard 078A9852BCF81DC4811E6EDCBFD121BE CAEQARiBgICNz_iR2hYiIGJjZTBjNDQxYWRhNTQ2ZTNiNmMzYzQ1YzMzMDA5ZjUw false false oss://bucket1/test.jpg Object Number is: 2 0.361000(s) elapsed
Common options
The following table describes the options you can add to the ls command to specify the items to be listed and how they can be listed.
Option | Description |
---|---|
-s |
Lists items in short format. |
-d |
Lists objects and subdirectories in the current directory, rather than recursively displaying all objects in all subdirectories. |
-m |
Lists only incomplete multipart upload tasks in the bucket. Objects are not displayed. |
-a |
Lists both objects and incomplete multipart upload tasks in the bucket. |
--limited-num |
Specifies the maximum number of returned entries. This option can be used together
with the --marker option to list objects by page.
|
--marker |
Specifies the bucket name, object name, or multipart upload ID from which you want to start listing. |
--upload-id-marker |
Specifies the multipart upload ID from which you want to start listing. |
--payer |
Specifies the payer of the request. If pay-by-requester is enabled, you can set this option to requester. |
--encoding-type |
Specifies the method used to encode the object name. If this option is specified, this value must be url. If this option is not specified, the object name is not encoded. Bucket names cannot be URL-encoded. |
--loglevel |
Specifies the log level. The default value is null, indicating that no log files are
generated. Valid values:
|
--all-versions |
Lists all versions of a specified object. This option can only be used for objects in a bucket that has versioning enabled. |
--version-id-marker |
Specifies the object version from which you want to start listing. |
Note For more information about common options, see View all supported options.