.TH "GCLOUD_ALPHA_STORAGE_OBJECTS_COMPOSE" 1



.SH "NAME"
.HP
gcloud alpha storage objects compose \- concatenate a sequence of objects into a new composite object



.SH "SYNOPSIS"
.HP
\f5gcloud alpha storage objects compose\fR \fISOURCE\fR [\fISOURCE\fR\ ...] \fIDESTINATION\fR [\fB\-\-additional\-headers\fR=\fIHEADER\fR=\fIVALUE\fR] [\fB\-\-custom\-contexts\fR=[\fICUSTOM_CONTEXTS_KEYS_AND_VALUES\fR,...]\ |\ \fB\-\-custom\-contexts\-file\fR=\fICUSTOM_CONTEXTS_FILE\fR] [\fB\-\-if\-generation\-match\fR=\fIGENERATION\fR\ \fB\-\-if\-metageneration\-match\fR=\fIMETAGENERATION\fR] [\fB\-\-retain\-until\fR=\fIDATETIME\fR\ \fB\-\-retention\-mode\fR=\fIRETENTION_MODE\fR] [\fIGCLOUD_WIDE_FLAG\ ...\fR]



.SH "DESCRIPTION"

\fB(ALPHA)\fR gcloud alpha 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
(https://cloud.google.com/storage/docs/composite\-objects).

There is a limit (currently 32) to the number of components that can be composed
in a single operation.



.SH "EXAMPLES"

The following command creates a new object \f5target.txt\fR by concatenating
\f5a.txt\fR and \f5b.txt\fR:

.RS 2m
$ gcloud alpha storage objects compose gs://bucket/a.txt \e
    gs://bucket/b.txt gs://bucket/target.txt
.RE

Contexts are merged from source objects on the composed object by default.
However, the following command overwrites custom contexts on composed object:

.RS 2m
$ gcloud alpha storage objects compose gs://bucket/a.txt \e
    gs://bucket/b.txt gs://bucket/target.txt \e
    \-\-custom\-contexts=key1=value1,key2=value2
.RE



.SH "POSITIONAL ARGUMENTS"

.RS 2m
.TP 2m
\fISOURCE\fR [\fISOURCE\fR ...]

The list of source objects that will be concatenated into a single object.

.TP 2m
\fIDESTINATION\fR

The destination object.


.RE
.sp

.SH "FLAGS"

.RS 2m
.TP 2m
\fB\-\-additional\-headers\fR=\fIHEADER\fR=\fIVALUE\fR

Includes arbitrary headers in storage API calls. Accepts a comma separated list
of key=value pairs, e.g. \f5header1=value1,header2=value2\fR. Overrides the
default \fBstorage/additional_headers\fR property value for this command
invocation.


.RE
.sp

.SH "OBJECT CONTEXTS FLAGS"

.RS 2m
.TP 2m

Group that allow users to handle object contexts.

At most one of these can be specified:


.RS 2m
.TP 2m
\fB\-\-custom\-contexts\fR=[\fICUSTOM_CONTEXTS_KEYS_AND_VALUES\fR,...]

Sets custom contexts on objects. The existing custom contexts (if any) would be
overwritten.

.TP 2m
\fB\-\-custom\-contexts\-file\fR=\fICUSTOM_CONTEXTS_FILE\fR

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):

.RS 2m
  {
    "key1": {"value": "value1"},
    "key2": {"value": "value2"}
  }
.RE

2. The following YAML document shows two key value pairs, i.e. (key1, value1)
and (key2, value2):

.RS 2m
  key1:
    value: value1
  key2:
    value: value2
.RE

Note: Currently object contexts only supports string format for values.


.RE
.RE
.sp

.SH "PRECONDITION FLAGS"

.RS 2m
.TP 2m
\fB\-\-if\-generation\-match\fR=\fIGENERATION\fR

Execute only if the generation matches the generation of the requested object.

.TP 2m
\fB\-\-if\-metageneration\-match\fR=\fIMETAGENERATION\fR

Execute only if the metageneration matches the metageneration of the requested
object.


.RE
.sp

.SH "RETENTION FLAGS"

.RS 2m
.TP 2m
\fB\-\-retain\-until\fR=\fIDATETIME\fR

Ensures the destination object is retained until the specified time in RFC 3339
format.

.TP 2m
\fB\-\-retention\-mode\fR=\fIRETENTION_MODE\fR

Sets the destination object retention mode to either "Locked" or "Unlocked".
When retention mode is "Locked", the retain until time can only be increased.
\fIRETENTION_MODE\fR must be one of: \fBLocked\fR, \fBUnlocked\fR.


.RE
.sp

.SH "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 \fB$ gcloud help\fR for details.



.SH "NOTES"

This command is currently in alpha and might change without notice. If this
command fails with API permission errors despite specifying the correct project,
you might be trying to access an API with an invitation\-only early access
allowlist. This variant is also available:

.RS 2m
$ gcloud storage objects compose
.RE