20
20
# executable files with reasonable names.
22
22
# 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
28
commands as _mod_commands,
37
def help(topic=None, outfile=None):
38
"""Write the help for the specific topic to outfile"""
42
indices = HelpIndices()
44
alias = _mod_commands.get_alias(topic)
46
topics = indices.search(topic)
48
for index, topic in topics[1:]:
49
shadowed_terms.append('%s%s' % (index.prefix,
50
topic.get_help_topic()))
52
outfile.write(source.get_help_text(shadowed_terms))
53
except errors.NoHelpTopic:
58
outfile.write("'bzr %s' is an alias for 'bzr %s'.\n" % (topic,
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())
62
140
def help_commands(outfile=None):
63
141
"""List all commands"""
142
from bzrlib.commands import (builtin_command_names,
143
plugin_command_names,
64
145
if outfile is None:
65
146
outfile = sys.stdout
66
outfile.write(_help_commands_to_text('commands'))
69
def _help_commands_to_text(topic):
70
"""Generate the help text for the list of commands"""
72
if topic == 'hidden-commands':
76
names = list(_mod_commands.all_command_names())
77
commands = ((n, _mod_commands.get_cmd_object(n)) for n in names)
78
shown_commands = [(n, o) for n, o in commands if o.hidden == hidden]
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]
79
151
max_name = max(len(n) for n, o in shown_commands)
80
152
indent = ' ' * (max_name + 1)
81
153
width = osutils.terminal_width() - 1
83
154
for cmd_name, cmd_object in sorted(shown_commands):
84
155
plugin_name = cmd_object.plugin_name()
85
156
if plugin_name is None:
95
166
helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
96
lines = textwrap.wrap(
97
helpstring, subsequent_indent=indent,
99
break_long_words=False)
167
lines = textwrap.wrap(helpstring, subsequent_indent=indent,
100
169
for line in lines:
101
out.append(line + '\n')
105
help_topics.topic_registry.register("commands",
106
_help_commands_to_text,
107
"Basic help for all commands",
108
help_topics.SECT_HIDDEN)
109
help_topics.topic_registry.register("hidden-commands",
110
_help_commands_to_text,
111
"All hidden commands",
112
help_topics.SECT_HIDDEN)
115
class HelpIndices(object):
116
"""Maintainer of help topics across multiple indices.
118
It is currently separate to the HelpTopicRegistry because of its ordered
119
nature, but possibly we should instead structure it as a search within the
120
registry and add ordering and searching facilities to the registry. The
121
registry would probably need to be restructured to support that cleanly
122
which is why this has been implemented in parallel even though it does as a
123
result permit searching for help in indices which are not discoverable via
126
Each index has a unique prefix string, such as "commands", and contains
127
help topics which can be listed or searched.
132
help_topics.HelpTopicIndex(),
133
_mod_commands.HelpCommandIndex(),
134
plugin.PluginsHelpIndex(),
137
def _check_prefix_uniqueness(self):
138
"""Ensure that the index collection is able to differentiate safely."""
140
for index in self.search_path:
141
prefixes.setdefault(index.prefix, []).append(index)
142
for prefix, indices in prefixes.items():
144
raise errors.DuplicateHelpPrefix(prefix)
146
def search(self, topic):
147
"""Search for topic across the help search path.
149
:param topic: A string naming the help topic to search for.
150
:raises: NoHelpTopic if none of the indexs in search_path have topic.
151
:return: A list of HelpTopics which matched 'topic'.
153
self._check_prefix_uniqueness()
155
for index in self.search_path:
156
result.extend([(index, _topic) for _topic in index.get_topics(topic)])
158
raise errors.NoHelpTopic(topic)
170
outfile.write(line + '\n')