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
17from __future__ import absolute_import
18
19from 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
122class 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