← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help.py

  • Committer: Martin Pool
  • Date: 2005-05-16 02:19:13 UTC
  • Revision ID: mbp@sourcefrog.net-20050516021913-3a933f871079e3fe
- patch from ddaa to create api/ directory 
  before building API docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help.py
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
16
 
17
 
# TODO: Some way to get a list of external commands (defined by shell
18
 
# scripts) so that they can be included in the help listing as well.
19
 
# It should be enough to just list the plugin directory and look for
20
 
# executable files with reasonable names.
21
 
 
22
 
# TODO: `help commands --all` should show hidden commands
23
 
 
24
17
global_help = \
25
18
"""Bazaar-NG -- a free distributed version-control tool
26
19
http://bazaar-ng.org/
27
20
 
28
 
WARNING: This is an unstable development version.
29
 
         Please keep backups.
30
 
 
31
 
Basic commands:
32
 
 
33
 
  bzr init           makes this directory a versioned branch
34
 
  bzr branch         make a copy of another branch
35
 
 
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
39
 
 
40
 
  bzr status         summarize changes in working copy
41
 
  bzr diff           show detailed diffs
42
 
 
43
 
  bzr merge          pull in changes from another branch
44
 
  bzr commit         save some or all changes
45
 
 
46
 
  bzr log            show history of changes
47
 
  bzr check          validate storage
48
 
 
49
 
  bzr help init      more help on e.g. init command
50
 
  bzr help commands  list all commands
 
21
**WARNING: THIS IS AN UNSTABLE DEVELOPMENT VERSION**
 
22
 
 
23
* Metadata format is not stable yet -- you may need to
 
24
  discard history in the future.
 
25
 
 
26
* Many commands unimplemented or partially implemented.
 
27
 
 
28
* Space-inefficient storage.
 
29
 
 
30
* No merge operators yet.
 
31
 
 
32
 
 
33
To make a branch, use 'bzr init' in an existing directory, then 'bzr
 
34
add' to make files versioned.  'bzr add .' will recursively add all
 
35
non-ignored files.
 
36
 
 
37
'bzr status' describes files that are unknown, ignored, or modified.
 
38
'bzr diff' shows the text changes to the tree or named files.
 
39
'bzr commit -m <MESSAGE>' commits all changes in that branch.
 
40
 
 
41
'bzr move' and 'bzr rename' allow you to rename files or directories.
 
42
'bzr remove' makes a file unversioned but keeps the working copy;
 
43
to delete that too simply delete the file.
 
44
 
 
45
'bzr log' shows a history of changes, and
 
46
'bzr info' gives summary statistical information.
 
47
'bzr check' validates all files are stored safely.
 
48
 
 
49
Files can be ignored by giving a path or a glob in .bzrignore at the
 
50
top of the tree.  Use 'bzr ignored' to see what files are ignored and
 
51
why, and 'bzr unknowns' to see files that are neither versioned or
 
52
ignored.
 
53
 
 
54
For more help on any command, type 'bzr help COMMAND', or 'bzr help
 
55
commands' for a list.
51
56
"""
52
57
 
53
58
 
54
 
import sys
55
 
 
56
 
 
57
 
def help(topic=None, outfile = None):
58
 
    if outfile == None:
59
 
        outfile = sys.stdout
 
59
 
 
60
def help(topic=None):
60
61
    if topic == None:
61
 
        outfile.write(global_help)
 
62
        print global_help
62
63
    elif topic == 'commands':
63
 
        help_commands(outfile = outfile)
 
64
        help_commands()
64
65
    else:
65
 
        help_on_command(topic, outfile = outfile)
66
 
 
67
 
 
68
 
def command_usage(cmd_object):
 
66
        help_on_command(topic)
 
67
 
 
68
 
 
69
def command_usage(cmdname, cmdclass):
69
70
    """Return single-line grammar for command.
70
71
 
71
72
    Only describes arguments, not options.
72
73
    """
73
 
    s = 'bzr ' + cmd_object.name() + ' '
74
 
    for aname in cmd_object.takes_args:
 
74
    s = cmdname + ' '
 
75
    for aname in cmdclass.takes_args:
75
76
        aname = aname.upper()
76
77
        if aname[-1] in ['$', '+']:
77
78
            aname = aname[:-1] + '...'
87
88
    return s
88
89
 
89
90
 
90
 
def help_on_command(cmdname, outfile=None):
91
 
    from bzrlib.commands import get_cmd_object
92
 
 
 
91
def help_on_command(cmdname):
93
92
    cmdname = str(cmdname)
94
93
 
95
 
    if outfile == None:
96
 
        outfile = sys.stdout
97
 
 
98
 
    cmd_object = get_cmd_object(cmdname)
99
 
 
100
 
    doc = cmd_object.help()
 
94
    from inspect import getdoc
 
95
    import commands
 
96
    topic, cmdclass = commands.get_cmd_class(cmdname)
 
97
 
 
98
    doc = getdoc(cmdclass)
101
99
    if doc == None:
102
100
        raise NotImplementedError("sorry, no detailed help yet for %r" % cmdname)
103
101
 
104
 
    print >>outfile, 'usage:', command_usage(cmd_object) 
105
 
 
106
 
    if cmd_object.aliases:
107
 
        print >>outfile, 'aliases:',
108
 
        print >>outfile, ', '.join(cmd_object.aliases)
109
 
 
110
 
    print >>outfile
111
 
 
112
 
    outfile.write(doc)
113
 
    if doc[-1] != '\n':
114
 
        outfile.write('\n')
115
 
    
116
 
    help_on_options(cmd_object.takes_options, outfile=None)
117
 
 
118
 
 
119
 
def help_on_options(options, outfile=None):
120
 
    from bzrlib.commands import SHORT_OPTIONS
 
102
    print 'usage:', command_usage(topic, cmdclass)
 
103
 
 
104
    if cmdclass.aliases:
 
105
        print 'aliases: ' + ', '.join(cmdclass.aliases)
 
106
    
 
107
    print doc
 
108
    
 
109
    help_on_option(cmdclass.takes_options)
 
110
 
 
111
 
 
112
def help_on_option(options):
 
113
    import commands
121
114
    
122
115
    if not options:
123
116
        return
124
117
    
125
 
    if outfile == None:
126
 
        outfile = sys.stdout
127
 
 
128
 
    outfile.write('\noptions:\n')
 
118
    print
 
119
    print 'options:'
129
120
    for on in options:
130
121
        l = '    --' + on
131
 
        for shortname, longname in SHORT_OPTIONS.items():
 
122
        for shortname, longname in commands.SHORT_OPTIONS.items():
132
123
            if longname == on:
133
124
                l += ', -' + shortname
134
125
                break
135
 
        outfile.write(l + '\n')
136
 
 
137
 
 
138
 
def help_commands(outfile=None):
 
126
        print l
 
127
 
 
128
 
 
129
def help_commands():
139
130
    """List all commands"""
140
 
    from bzrlib.commands import (builtin_command_names,
141
 
                                 plugin_command_names,
142
 
                                 get_cmd_object)
143
 
 
144
 
    if outfile == None:
145
 
        outfile = sys.stdout
146
 
 
147
 
    names = set()                       # to eliminate duplicates
148
 
    names.update(builtin_command_names())
149
 
    names.update(plugin_command_names())
150
 
    names = list(names)
151
 
    names.sort()
152
 
 
153
 
    for cmd_name in names:
154
 
        cmd_object = get_cmd_object(cmd_name)
155
 
        if cmd_object.hidden:
 
131
    import inspect
 
132
    import commands
 
133
    
 
134
    accu = []
 
135
    for cmdname, cmdclass in commands.get_all_cmds():
 
136
        accu.append((cmdname, cmdclass))
 
137
    accu.sort()
 
138
    for cmdname, cmdclass in accu:
 
139
        if cmdclass.hidden:
156
140
            continue
157
 
        print >>outfile, command_usage(cmd_object)
158
 
        cmd_help = cmd_object.help()
159
 
        if cmd_help:
160
 
            firstline = cmd_help.split('\n', 1)[0]
161
 
            print >>outfile, '    ' + firstline
162
 
        
 
141
        print command_usage(cmdname, cmdclass)
 
142
        help = inspect.getdoc(cmdclass)
 
143
        if help:
 
144
            print "    " + help.split('\n', 1)[0]
 
145
            
 
146