stat - Display object status

Synopsis

gsutil stat url...

Description

The stat command outputs object metadata for the specified object URLs. It is similar to running:

gsutil ls -L gs://some-bucket/some-object

but is more efficient because it avoids listing objects and gets the minimum necessary amount of object metadata. Moreover, because it avoids listing objects (which for some storage providers are eventually consistent) the gsutil stat command provides a strongly consistent way to check for the existence (and read the metadata) of an object.

The gsutil stat command does, however, make listing object requests if you specify URLs using wildcards.

If run with the gsutil -q option nothing is printed, e.g.:

gsutil -q stat gs://some-bucket/some-object

This behavior can be useful when writing scripts: even though nothing is printed from the command, it still has an exit status of 0 for an existing object and 1 for a non-existent object.

gsutil -q stat gs://some-bucket/some-subdir/

gsutil looks for information about an object called "some-subdir/" (with a trailing slash) inside the bucket "some-bucket", as opposed to operating on objects nested under gs://some-bucket/some-subdir/. Unless you actually have an object with that name, the operation fails. However, you can use the stat command on objects within subdirectories. For example, this command works as expected:

gsutil -q stat gs://some-bucket/some-subdir/file.txt