20
22
# executable files with reasonable names.
22
24
# TODO: `help commands --all` should show hidden commands
24
from bzrlib import osutils
27
"""Bazaar -- a free distributed version-control tool
28
http://bazaar-vcs.org/
32
bzr init makes this directory a versioned branch
33
bzr branch make a copy of another branch
35
bzr add make files or directories versioned
36
bzr ignore ignore a file or pattern
37
bzr mv move or rename a versioned file
39
bzr status summarize changes in working copy
40
bzr diff show detailed diffs
42
bzr merge pull in changes from another branch
43
bzr commit save some or all changes
45
bzr log show history of changes
46
bzr check validate storage
48
bzr help init more help on e.g. init command
49
bzr help commands list all commands
56
def help(topic=None, outfile = None):
60
outfile.write(global_help)
61
elif topic == 'commands':
62
help_commands(outfile = outfile)
64
help_on_command(topic, outfile = outfile)
67
def command_usage(cmd_object):
68
"""Return single-line grammar for command.
70
Only describes arguments, not options.
72
s = 'bzr ' + cmd_object.name() + ' '
73
for aname in cmd_object.takes_args:
75
if aname[-1] in ['$', '+']:
76
aname = aname[:-1] + '...'
77
elif aname[-1] == '?':
78
aname = '[' + aname[:-1] + ']'
79
elif aname[-1] == '*':
80
aname = '[' + aname[:-1] + '...]'
89
def print_command_plugin(cmd_object, outfile, format):
90
"""Print the plugin that provides a command object, if any.
92
If the cmd_object is provided by a plugin, prints the plugin name to
93
outfile using the provided format string.
95
plugin_name = cmd_object.plugin_name()
96
if plugin_name is not None:
97
out_str = '(From plugin "%s")' % plugin_name
98
outfile.write(format % out_str)
101
def help_on_command(cmdname, outfile=None):
102
from bzrlib.commands import get_cmd_object
104
cmdname = str(cmdname)
109
cmd_object = get_cmd_object(cmdname)
111
doc = cmd_object.help()
113
raise NotImplementedError("sorry, no detailed help yet for %r" % cmdname)
115
print >>outfile, 'usage:', command_usage(cmd_object)
117
if cmd_object.aliases:
118
print >>outfile, 'aliases:',
119
print >>outfile, ', '.join(cmd_object.aliases)
123
print_command_plugin(cmd_object, outfile, '%s\n\n')
128
help_on_command_options(cmd_object, outfile)
131
def help_on_command_options(cmd, outfile=None):
132
from bzrlib.option import Option, get_optparser
135
options = cmd.options()
137
outfile.write(get_optparser(options).format_option_help())
29
commands as _mod_commands,
39
def help(topic=None, outfile=None):
40
"""Write the help for the specific topic to outfile"""
42
outfile = ui.ui_factory.make_output_stream()
44
indices = HelpIndices()
46
alias = _mod_commands.get_alias(topic)
48
topics = indices.search(topic)
50
for index, topic_obj in topics[1:]:
51
shadowed_terms.append('%s%s' % (index.prefix,
52
topic_obj.get_help_topic()))
54
outfile.write(source.get_help_text(shadowed_terms))
55
except errors.NoHelpTopic:
60
outfile.write("'bzr %s' is an alias for 'bzr %s'.\n" % (topic,
140
64
def help_commands(outfile=None):
141
65
"""List all commands"""
142
from bzrlib.commands import (builtin_command_names,
143
plugin_command_names,
145
66
if outfile is None:
147
names = set(builtin_command_names()) # to eliminate duplicates
148
names.update(plugin_command_names())
149
commands = ((n, get_cmd_object(n)) for n in names)
150
shown_commands = [(n, o) for n, o in commands if not o.hidden]
67
outfile = ui.ui_factory.make_output_stream()
68
outfile.write(_help_commands_to_text('commands'))
71
def _help_commands_to_text(topic):
72
"""Generate the help text for the list of commands"""
74
if topic == 'hidden-commands':
78
names = list(_mod_commands.all_command_names())
79
commands = ((n, _mod_commands.get_cmd_object(n)) for n in names)
80
shown_commands = [(n, o) for n, o in commands if o.hidden == hidden]
151
81
max_name = max(len(n) for n, o in shown_commands)
152
82
indent = ' ' * (max_name + 1)
153
width = osutils.terminal_width() - 1
83
width = osutils.terminal_width()
85
width = osutils.default_terminal_width
86
# we need one extra space for terminals that wrap on last char
154
89
for cmd_name, cmd_object in sorted(shown_commands):
155
90
plugin_name = cmd_object.plugin_name()
156
91
if plugin_name is None:
166
101
helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
167
lines = textwrap.wrap(helpstring, subsequent_indent=indent,
102
lines = utextwrap.wrap(
103
helpstring, subsequent_indent=indent,
105
break_long_words=False)
169
106
for line in lines:
170
outfile.write(line + '\n')
107
out.append(line + '\n')
111
help_topics.topic_registry.register("commands",
112
_help_commands_to_text,
113
"Basic help for all commands",
114
help_topics.SECT_HIDDEN)
115
help_topics.topic_registry.register("hidden-commands",
116
_help_commands_to_text,
117
"All hidden commands",
118
help_topics.SECT_HIDDEN)
121
class HelpIndices(object):
122
"""Maintainer of help topics across multiple indices.
124
It is currently separate to the HelpTopicRegistry because of its ordered
125
nature, but possibly we should instead structure it as a search within the
126
registry and add ordering and searching facilities to the registry. The
127
registry would probably need to be restructured to support that cleanly
128
which is why this has been implemented in parallel even though it does as a
129
result permit searching for help in indices which are not discoverable via
132
Each index has a unique prefix string, such as "commands", and contains
133
help topics which can be listed or searched.
138
help_topics.HelpTopicIndex(),
139
_mod_commands.HelpCommandIndex(),
140
plugin.PluginsHelpIndex(),
141
help_topics.ConfigOptionHelpIndex(),
144
def _check_prefix_uniqueness(self):
145
"""Ensure that the index collection is able to differentiate safely."""
147
for index in self.search_path:
148
prefixes.setdefault(index.prefix, []).append(index)
149
for prefix, indices in prefixes.items():
151
raise errors.DuplicateHelpPrefix(prefix)
153
def search(self, topic):
154
"""Search for topic across the help search path.
156
:param topic: A string naming the help topic to search for.
157
:raises: NoHelpTopic if none of the indexs in search_path have topic.
158
:return: A list of HelpTopics which matched 'topic'.
160
self._check_prefix_uniqueness()
162
for index in self.search_path:
163
result.extend([(index, _topic) for _topic in index.get_topics(topic)])
165
raise errors.NoHelpTopic(topic)