tools/telemetry/third_party/gsutilz/gslib/addlhelp/command_opts.py

   1 # -*- coding: utf-8 -*-
   2 # Copyright 2012 Google Inc. All Rights Reserved.
   3 #
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15 """Additional help about gsutil command-level options."""
  16
  17 from __future__ import absolute_import
  18
  19 from gslib.help_provider import HelpProvider
  20
  21 _DETAILED_HELP_TEXT = ("""
  22 <B>SYNOPSIS</B>
  23   Top-level gsutil Options
  24
  25
  26 <B>DESCRIPTION</B>
  27   gsutil supports separate options for the top-level gsutil command and
  28   the individual sub-commands (like cp, rm, etc.) The top-level options
  29   control behavior of gsutil that apply across commands. For example, in
  30   the command:
  31
  32     gsutil -m cp -p file gs://bucket/obj
  33
  34   the -m option applies to gsutil, while the -p option applies to the cp
  35   sub-command.
  36
  37
  38 <B>OPTIONS</B>
  39   -D          Shows HTTP requests/headers and additional debug info needed when
  40               posting support requests.
  41
  42   -DD         Shows HTTP requests/headers, additional debug info plus HTTP
  43               upstream payload.
  44
  45   -h          Allows you to specify certain HTTP headers, for example:
  46
  47                 gsutil -h "Cache-Control:public,max-age=3600" \\
  48                        -h "Content-Type:text/html" cp ...
  49
  50               Note that you need to quote the headers/values that
  51               contain spaces (such as "Content-Disposition: attachment;
  52               filename=filename.ext"), to avoid having the shell split them
  53               into separate arguments.
  54
  55               The following headers are supported:
  56               Cache-Control
  57               Content-Disposition
  58               Content-Encoding
  59               Content-Language
  60               Content-MD5
  61               Content-Type
  62               Custom metadata headers with a matching Cloud Storage Provider
  63               prefix, such as:
  64
  65                 x-goog-meta-
  66
  67               Note that for gs:// URLs, the Cache Control header is specific to
  68               the API being used. The XML API will accept any cache control
  69               headers and return them during object downloads.  The JSON API
  70               respects only the public, private, no-cache, and max-age cache
  71               control headers, and may add its own no-transform directive even
  72               if it was not specified. See 'gsutil help apis' for more
  73               information on gsutil's interaction with APIs.
  74
  75               See also "gsutil help setmeta" for the ability to set metadata
  76               fields on objects after they have been uploaded.
  77
  78   -m          Causes supported operations (acl ch, acl set, cp, mv, rm, rsync,
  79               and setmeta) to run in parallel. This can significantly improve
  80               performance if you are performing operations on a large number of
  81               files over a reasonably fast network connection.
  82
  83               gsutil performs the specified operation using a combination of
  84               multi-threading and multi-processing, using a number of threads
  85               and processors determined by the parallel_thread_count and
  86               parallel_process_count values set in the boto configuration
  87               file. You might want to experiment with these values, as the
  88               best values can vary based on a number of factors, including
  89               network speed, number of CPUs, and available memory.
  90
  91               Using the -m option may make your performance worse if you
  92               are using a slower network, such as the typical network speeds
  93               offered by non-business home network plans. It can also make
  94               your performance worse for cases that perform all operations
  95               locally (e.g., gsutil rsync, where both source and desination URLs
  96               are on the local disk), because it can "thrash" your local disk.
  97
  98               If a download or upload operation using parallel transfer fails
  99               before the entire transfer is complete (e.g. failing after 300 of
 100               1000 files have been transferred), you will need to restart the
 101               entire transfer.
 102
 103               Also, although most commands will normally fail upon encountering
 104               an error when the -m flag is disabled, all commands will
 105               continue to try all operations when -m is enabled with multiple
 106               threads or processes, and the number of failed operations (if any)
 107               will be reported at the end of the command's execution.
 108
 109               WARNING: If you use the gsutil -m option when copying data
 110               between versioned buckets, object version ordering will not be
 111               preserved. For more information see the
 112               "COPYING VERSIONED BUCKETS" section under
 113               'gsutil help versions'.
 114
 115   -o          Set/override values in the boto configuration value, in the format
 116               <section>:<name>=<value>, e.g. gsutil -o "Boto:proxy=host" ...
 117               This will not pass the option to gsutil integration tests, which
 118               run in a separate process.
 119
 120   -q          Causes gsutil to perform operations quietly, i.e., without
 121               reporting progress indicators of files being copied or removed,
 122               etc. Errors are still reported. This option can be useful for
 123               running gsutil from a cron job that logs its output to a file, for
 124               which the only information desired in the log is failures.
 125 """)
 126
 127
 128 class CommandOptions(HelpProvider):
 129   """Additional help about gsutil command-level options."""
 130
 131   # Help specification. See help_provider.py for documentation.
 132   help_spec = HelpProvider.HelpSpec(
 133       help_name='options',
 134       help_name_aliases=['arg', 'args', 'cli', 'opt', 'opts'],
 135       help_type='additional_help',
 136       help_one_line_summary='Top-Level Command-Line Options',
 137       help_text=_DETAILED_HELP_TEXT,
 138       subcommand_help_text={},
 139   )