How to Read Information (ls and stat) About Buckets with the gsutil Utility

By Matthew Scarpino

The ls and stat commands of the gsutil utility provide information about buckets and objects in Cloud Storage. The simplest usage of ls is gsutil ls, which lists all of the buckets associated with the current GCP project.

One interesting feature of ls is that it recognizes the virtual hierarchy of objects. For example, suppose that gs://mybucket contains /mydir/a.txt, /mydir/b.txt, and /newdir/c.txt. The command gsutil ls gs://mybucket prints /mydir and /newdir, but none of the underlying objects. But if you set the -r flag, the entire contents of a bucket will be displayed. The following command demonstrates this:

gsutil ls -r gs://mybucket

Another useful flag is -l, which tells ls to print detailed output for each object of interest. These details include object sizes, creation sizes, and ownership. The -L flag prints even more information, including the content type, storage class, and update time of each object of interest.

If you want detailed information about one object, stat is more efficient than ls -L. As an example, the following command prints detailed information about the training.dat object in mybucket/mydir:

gsutil stat gs://mybucket/mydir/training.dat

The exit code of this command will equal 1 if the object exists and 0 if it doesn’t. One important difference between stat and ls is that stat only provides information about objects.