setmeta - Set metadata on already uploaded objects

Important: gsutil is not the recommended CLI for Cloud Storage. Use gcloud storage commands in the Google Cloud CLI instead.

Synopsis

gsutil setmeta -h [header:value|header] ... url...

Description

The gsutil setmeta command allows you to set or remove the metadata on one or more objects. It takes one or more header arguments followed by one or more URLs, where each header argument is in one of two forms:

• If you specify header:value, it sets the provided value for the given header on all applicable objects.

• If you specify header (with no value), it removes the given header from all applicable objects.

For example, the following command sets the Content-Type and Cache-Control headers while also removing the Content-Disposition header on the specified objects:

gsutil setmeta -h "Content-Type:text/html" \
  -h "Cache-Control:public, max-age=3600" \
  -h "Content-Disposition" gs://bucket/*.html

If you have a large number of objects to update you might want to use the gsutil -m option, to perform a parallel (multi-threaded/multi-processing) update:

gsutil -m setmeta -h "Content-Type:text/html" \
  -h "Cache-Control:public, max-age=3600" \
  -h "Content-Disposition" gs://bucket/*.html

You can also use the setmeta command to set custom metadata on an object:

gsutil setmeta -h "x-goog-meta-icecreamflavor:vanilla" gs://bucket/object

Custom metadata is always prefixed in gsutil with x-goog-meta-. This distinguishes it from standard request headers. Other tools that send and receive object metadata by using the request body do not use this prefix.

While gsutil supports custom metadata with arbitrary Unicode values, note that when setting metadata using the XML API, which sends metadata as HTTP headers, Unicode characters are encoded using UTF-8, then url-encoded to ASCII. For example:

gsutil setmeta -h "x-goog-meta-foo: ã" gs://bucket/object

stores the custom metadata key-value pair of foo and %C3%A3. Subsequently, running ls -L using the JSON API to list the object's metadata prints %C3%A3, while ls -L using the XML API url-decodes this value automatically, printing the character ã.

The setmeta command reads each object's current generation and metageneration and uses those as preconditions unless they are otherwise specified by top-level arguments. For example, the following command sets the custom metadata icecreamflavor:vanilla if the current live object has a metageneration of 2:

gsutil -h "x-goog-if-metageneration-match:2" setmeta
  -h "x-goog-meta-icecreamflavor:vanilla"

See Object metadata for more information about object metadata.

Options

-h

Specifies a header:value to be added, or header to be removed, from each named object.