rewrite - Rewrite objects

rewrite - Rewrite objects

Synopsis

gsutil rewrite -k [-f] [-r] url...
gsutil rewrite -k [-f] [-r] -I

Description

The gsutil rewrite command rewrites cloud objects, applying the specified transformations to them. The transformation(s) are atomic and applied based on the input transformation flags. Object metadata values are preserved unless altered by a transformation.

The -k flag is supported to add, rotate, or remove encryption keys on objects. For example, the command:

gsutil rewrite -k gs://bucket/**

will update all objects in gs://bucket with the current encryption key from your boto config file.

You can also use the -r option to specify recursive object transform; this is synonymous with the ** wildcard. Thus, either of the following two commands will perform encryption key transforms on gs://bucket/subdir and all objects and subdirectories under it:

gsutil rewrite -k gs://bucket/subdir**
gsutil rewrite -k -r gs://bucket/subdir

The rewrite command acts only on live object versions, so specifying a URL with a generation will fail. If you want to rewrite an archived generation, first copy it to the live version, then rewrite it, for example:

gsutil cp gs://bucket/object#123 gs://bucket/object
gsutil rewrite -k gs://bucket/object

You can use the -s option to specify a new storage class for objects. For example, the command:

gsutil rewrite -s nearline gs://bucket/foo

will rewrite the object, changing its storage class to nearline.

The rewrite command will skip objects that are already in the desired state. For example, if you run:

gsutil rewrite -k gs://bucket/**

and gs://bucket contains objects that already match the encryption configuration, gsutil will skip rewriting those objects and only rewrite objects that do not match the encryption configuration. If you specify multiple transformations, gsutil will only skip those that would not change the object's state. For example, if you run:

gsutil rewrite -s nearline -k gs://bucket/**

and gs://bucket contains objects that already match the encryption configuration but have a storage class of standard, the only transformation applied to those objects would be the change in storage class.

You can pass a list of URLs (one per line) to rewrite on stdin instead of as command line arguments by using the -I option. This allows you to use gsutil in a pipeline to rewrite objects identified by a program, such as:

some_program | gsutil -m rewrite -k -I

The contents of stdin can name cloud URLs and wildcards of cloud URLs.

The rewrite command requires OWNER permissions on each object to preserve object ACLs. You can bypass this by using the -O flag, which will cause gsutil not to read the object's ACL and instead apply the default object ACL to the rewritten object:

gsutil rewrite -k -O gs://bucket/**

Options

-f Continues silently (without printing error messages) despite errors when rewriting multiple objects. If some of the objects could not be rewritten, gsutil's exit status will be non-zero even if this flag is set. This option is implicitly set when running "gsutil -m rewrite ...".
-I Causes gsutil to read the list of objects to rewrite from stdin. This allows you to run a program that generates the list of objects to rewrite.
-k Rewrite the objects to the current encryption key specific in your boto configuration file. If encryption_key is specified, encrypt all objects with this key. If encryption_key is unspecified, decrypt all objects. See ``gsutil help encryption </storage/docs/gsutil/addlhelp/SupplyingYourOwnEncryptionKeys>`_` for details on encryption configuration.
-O Rewrite objects with the bucket's default object ACL instead of the existing object ACL. This is needed if you do not have OWNER permission on the object.
-R, -r The -R and -r options are synonymous. Causes bucket or bucket subdirectory contents to be rewritten recursively.
-s <class> Rewrite objects using the specified storage class.

Send feedback about...

Cloud Storage Documentation