- NAME
-
- gcloud storage objects compose - concatenate a sequence of objects into a new composite object
- SYNOPSIS
-
-
gcloud storage objects composeSOURCE[SOURCE…]DESTINATION[--additional-headers=HEADER=VALUE] [--delete-source-objects] [--clear-custom-contexts|--custom-contexts=[CUSTOM_CONTEXTS_KEYS_AND_VALUES, …] |--custom-contexts-file=CUSTOM_CONTEXTS_FILE] [--if-generation-match=GENERATION--if-metageneration-match=METAGENERATION] [--retain-until=DATETIME--retention-mode=RETENTION_MODE] [GCLOUD_WIDE_FLAG …]
-
- DESCRIPTION
- gcloud storage objects compose creates a new object whose content is the
concatenation of a given sequence of source objects in the same bucket. For more
information, please see: composite objects
documentation
.
There is a limit (currently 32) to the number of components that can be composed in a single operation.
- EXAMPLES
- The following command creates a new object
target.txtby concatenatinga.txtandb.txt:gcloud storage objects compose gs://bucket/a.txt gs://bucket/b.txt gs://bucket/target.txtContexts are merged from source objects on the composed object by default. However, the following command overwrites custom contexts on composed object:
gcloud storage objects compose gs://bucket/a.txt gs://bucket/b.txt gs://bucket/target.txt --custom-contexts = key1 = value1,key2 = value2The following command creates a new object
target.txtby concatenatinga.txtandb.txt, and deletes the source objects after a successful composition:gcloud storage objects compose gs://bucket/a.txt gs://bucket/b.txt gs://bucket/target.txt --delete-source-objects - POSITIONAL ARGUMENTS
-
-
SOURCE[SOURCE…] - The list of source objects that will be concatenated into a single object.
-
DESTINATION - The destination object.
-
- FLAGS
-
-
--additional-headers=HEADER=VALUE - Includes arbitrary headers in storage API calls. Accepts a comma separated list
of key=value pairs, e.g.
header1=value1,header2=value2. Overrides the defaultstorage/additional_headersproperty value for this command invocation. -
--delete-source-objects - If set, the source objects will be deleted after a successful composition. Note that this deletion bypasses the soft delete policy if configured on the bucket.
-
- OBJECT CONTEXTS FLAGS
-
- Group that allow users to handle object contexts.
At most one of these can be specified:
-
--clear-custom-contexts - Clears all custom contexts on objects.
-
--custom-contexts=[CUSTOM_CONTEXTS_KEYS_AND_VALUES,…] - Sets custom contexts on objects. The existing custom contexts (if any) would be overwritten.
-
--custom-contexts-file=CUSTOM_CONTEXTS_FILE - Path to a local JSON or YAML file containing custom contexts one wants to set on
an object. For example:
1. The following JSON document shows two key value pairs, i.e. (key1, value1) and (key2, value2):
{ "key1" : { "value" : "value1" } , "key2" : { "value" : "value2" } }
2. The following YAML document shows two key value pairs, i.e. (key1, value1) and (key2, value2):
key1: value: value1 key2: value: value2
Note: Currently object contexts only supports string format for values.
-
- Group that allow users to handle object contexts.
- PRECONDITION FLAGS
-
-
--if-generation-match=GENERATION - Execute only if the generation matches the generation of the requested object.
- Execute only if the metageneration matches the metageneration of the requested object.
-
- RETENTION FLAGS
-
-
--retain-until=DATETIME - Ensures the destination object is retained until the specified time in RFC 3339 format.
-
--retention-mode=RETENTION_MODE - Sets the destination object retention mode to either "Locked" or "Unlocked".
When retention mode is "Locked", the retain until time can only be increased.
RETENTION_MODEmust be one of:Locked,Unlocked.
-
- GCLOUD WIDE FLAGS
- These flags are available to all commands:
--access-token-file,--account,--billing-project,--configuration,--flags-file,--flatten,--format,--help,--impersonate-service-account,--log-http,--project,--quiet,--trace-token,--user-output-enabled,--verbosity.Run
$ gcloud helpfor details. - NOTES
- This variant is also available:
gcloud alpha storage objects compose
gcloud storage objects compose
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-05-27 UTC.

