Object Versioning and Concurrency Control

Overview

Versioning-enabled buckets maintain noncurrent versions of objects, providing a way to un-delete data that you accidentally deleted, or to retrieve older versions of your data. Noncurrent objects are ignored by gsutil commands unless you indicate it should do otherwise by setting a relevant command flag or by including a specific generation number in your command. For example, wildcards like * and ** do not, by themselves, act on noncurrent object versions.

When using gsutil cp, you cannot specify a version-specific URL as the destination, because writes to Cloud Storage always create a new version. Trying to specify a version-specific URL as the destination of gsutil cp results in an error. When you specify a noncurrent object as a source in a copy command, you always create a new object version and retain the original (even when using the command to restore a live version). You can use the gsutil mv command to simultaneously restore an object version and remove the noncurrent copy that was used as the source.

You can turn versioning on or off for a bucket at any time. Turning versioning off leaves existing object versions in place and simply causes the bucket to delete the existing live version of the object whenever a new version is uploaded.

Regardless of whether you have enabled versioning on a bucket, every object has two associated positive integer fields:

  • the generation, which is updated when a new object replaces an existing object with the same name. Note that there is no guarantee that generation numbers increase for successive versions, only that each new version has a unique generation number.
  • the metageneration, which identifies the metadata generation. It starts at 1; is updated every time the metadata (e.g., ACL or Content-Type) for a given content generation is updated; and gets reset when the generation number changes.

Of these two integers, only the generation is used when working with versioned data. Both generation and metageneration can be used with concurrency control.

To learn more about versioning and concurrency, see the following documentation: