22
24
# TODO: `help commands --all` should show hidden commands
25
"""Bazaar-NG -- a free distributed version-control tool
28
WARNING: This is an unstable development version.
33
bzr init makes this directory a versioned branch
34
bzr branch make a copy of another branch
36
bzr add make files or directories versioned
37
bzr ignore ignore a file or pattern
38
bzr mv move or rename a versioned file
40
bzr status summarize changes in working copy
41
bzr diff show detailed diffs
43
bzr merge pull in changes from another branch
44
bzr commit save some or all changes
46
bzr log show history of changes
47
bzr check validate storage
49
bzr help init more help on e.g. init command
50
bzr help commands list all commands
57
def help(topic=None, outfile = None):
61
outfile.write(global_help)
62
elif topic == 'commands':
63
help_commands(outfile = outfile)
65
help_on_command(topic, outfile = outfile)
68
def command_usage(cmd_object):
69
"""Return single-line grammar for command.
71
Only describes arguments, not options.
73
s = 'bzr ' + cmd_object.name() + ' '
74
for aname in cmd_object.takes_args:
76
if aname[-1] in ['$', '+']:
77
aname = aname[:-1] + '...'
78
elif aname[-1] == '?':
79
aname = '[' + aname[:-1] + ']'
80
elif aname[-1] == '*':
81
aname = '[' + aname[:-1] + '...]'
90
def help_on_command(cmdname, outfile=None):
91
from bzrlib.commands import get_cmd_object
93
cmdname = str(cmdname)
98
cmd_object = get_cmd_object(cmdname)
100
doc = cmd_object.help()
102
raise NotImplementedError("sorry, no detailed help yet for %r" % cmdname)
104
print >>outfile, 'usage:', command_usage(cmd_object)
106
if cmd_object.aliases:
107
print >>outfile, 'aliases:',
108
print >>outfile, ', '.join(cmd_object.aliases)
115
help_on_command_options(cmd_object, outfile=None)
118
def help_on_command_options(cmd, outfile=None):
119
from bzrlib.option import Option
120
options = cmd.options()
125
outfile.write('\noptions:\n')
126
for option_name, option in sorted(options.items()):
127
l = ' --' + option_name
128
if option.type is not None:
129
l += ' ' + option.argname.upper()
130
short_name = option.short_name()
132
assert len(short_name) == 1
133
l += ', -' + shortname
134
l += (30 - len(l)) * ' ' + option.help
135
# TODO: split help over multiple lines with correct indenting and
137
outfile.write(l + '\n')
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,
149
names = set() # to eliminate duplicates
150
names.update(builtin_command_names())
151
names.update(plugin_command_names())
155
for cmd_name in names:
156
cmd_object = get_cmd_object(cmd_name)
157
if cmd_object.hidden:
159
print >>outfile, command_usage(cmd_object)
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]
81
max_name = max(len(n) for n, o in shown_commands)
82
indent = ' ' * (max_name + 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
89
for cmd_name, cmd_object in sorted(shown_commands):
90
plugin_name = cmd_object.plugin_name()
91
if plugin_name is None:
94
plugin_name = ' [%s]' % plugin_name
160
96
cmd_help = cmd_object.help()
162
98
firstline = cmd_help.split('\n', 1)[0]
163
print >>outfile, ' ' + firstline
101
helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
102
lines = utextwrap.wrap(
103
helpstring, subsequent_indent=indent,
105
break_long_words=False)
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)