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 -o Set/override values in the boto configuration value, in the format 110 <section>:<name>=<value>, e.g. gsutil -o "Boto:proxy=host" ... 111 This will not pass the option to gsutil integration tests, which 112 run in a separate process. 113 114 -q Causes gsutil to perform operations quietly, i.e., without 115 reporting progress indicators of files being copied or removed, 116 etc. Errors are still reported. This option can be useful for 117 running gsutil from a cron job that logs its output to a file, for 118 which the only information desired in the log is failures. 119 """) 120 121 122 class CommandOptions(HelpProvider): 123 """Additional help about gsutil command-level options.""" 124 125 # Help specification. See help_provider.py for documentation. 126 help_spec = HelpProvider.HelpSpec( 127 help_name='options', 128 help_name_aliases=['arg', 'args', 'cli', 'opt', 'opts'], 129 help_type='additional_help', 130 help_one_line_summary='Top-Level Command-Line Options', 131 help_text=_DETAILED_HELP_TEXT, 132 subcommand_help_text={}, 133 ) 134
