Roll version of gsutil to 4.15.

third_party/gsutil/gslib/addlhelp/metadata.py

 # -*- coding: utf-8 -*-
 # Copyright 2012 Google Inc. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
@@ skipping 67 matching lines @@
   ".webp" was recognized by the server-side content detection system, but
   not by gsutil.)
 
 
 <B>CACHE-CONTROL</B>
   Another commonly set piece of metadata is Cache-Control, which allows
   you to control whether and for how long browser and Internet caches are
   allowed to cache your objects. Cache-Control only applies to objects with
   a public-read ACL. Non-public data are not cacheable.
 
-  Here's an example of uploading an object set to allow caching:
+  Here's an example of uploading a set of objects to allow caching:
 
     gsutil -h "Cache-Control:public,max-age=3600" cp -a public-read \\
            -r html gs://bucket/html
 
   This command would upload all files in the html directory (and subdirectories)
   and make them publicly readable and cacheable, with cache expiration of
   one hour.
 
   Note that if you allow caching, at download time you may see older versions
   of objects after uploading a newer replacement object. Note also that because
   objects can be cached at various places on the Internet there is no way to
   force a cached object to expire globally (unlike the way you can force your
-  browser to refresh its cache).
+  browser to refresh its cache). If you want to prevent caching of publicly
+  readable objects you should set a Cache-Control:private header on the object.
+  You can do this with a command such as:
+
+    gsutil -h Cache-Control:private cp -a public-read file.png gs://your-bucket
 
   Another use of the Cache-Control header is through the "no-transform" value,
   which instructs Google Cloud Storage to not apply any content transformations
   based on specifics of a download request, such as removing gzip
   content-encoding for incompatible clients.  Note that this parameter is only
   respected by the XML API. The Google Cloud Storage JSON API respects only the
   no-cache and max-age Cache-Control parameters.
 
-  Note that if you upload an object with a public-read ACL and don't include a
-  Cache-Control header, it will be served with a Cache-Control header allowing
-  the object to be cached for 3600 seconds. This will not happen if the object
-  is uploaded with a non-public ACL and then changed to public. Moreover, if you
-  upload an object with a public-read ACL and later change the ACL not to be
-  public-read, the object will no longer be served with the default
-  Cache-Control header noted above (so will be served as not cacheable).
-  
   For details about how to set the Cache-Control header see
   "gsutil help setmeta".
 
 
 <B>CONTENT-ENCODING</B>
   You can specify a Content-Encoding to indicate that an object is compressed
   (for example, with gzip compression) while maintaining its Content-Type.
   You will need to ensure that the files have been compressed using the
   specified Content-Encoding before using gsutil to upload them. Consider the
   following example for Linux:
@@ skipping 74 matching lines @@
   help_spec = HelpProvider.HelpSpec(
       help_name='metadata',
       help_name_aliases=[
           'cache-control', 'caching', 'content type', 'mime type', 'mime',
           'type'],
       help_type='additional_help',
       help_one_line_summary='Working With Object Metadata',
       help_text=_DETAILED_HELP_TEXT,
       subcommand_help_text={},
   )