~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help.py

  • Committer: Martin Pool
  • Date: 2005-07-11 03:42:53 UTC
  • Revision ID: mbp@sourcefrog.net-20050711034253-412281abeb9f56ad
doc

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
 
65
70
        help_on_command(topic, outfile = outfile)
66
71
 
67
72
 
68
 
def command_usage(cmd_object):
 
73
def command_usage(cmdname, cmdclass):
69
74
    """Return single-line grammar for command.
70
75
 
71
76
    Only describes arguments, not options.
72
77
    """
73
 
    s = 'bzr ' + cmd_object.name() + ' '
74
 
    for aname in cmd_object.takes_args:
 
78
    s = cmdname + ' '
 
79
    for aname in cmdclass.takes_args:
75
80
        aname = aname.upper()
76
81
        if aname[-1] in ['$', '+']:
77
82
            aname = aname[:-1] + '...'
87
92
    return s
88
93
 
89
94
 
90
 
def help_on_command(cmdname, outfile=None):
91
 
    from bzrlib.commands import get_cmd_object
92
 
 
 
95
def help_on_command(cmdname, outfile = None):
93
96
    cmdname = str(cmdname)
94
97
 
95
98
    if outfile == None:
96
99
        outfile = sys.stdout
97
100
 
98
 
    cmd_object = get_cmd_object(cmdname)
 
101
    from inspect import getdoc
 
102
    import commands
 
103
    topic, cmdclass = commands.get_cmd_class(cmdname)
99
104
 
100
 
    doc = cmd_object.help()
 
105
    doc = getdoc(cmdclass)
101
106
    if doc == None:
102
107
        raise NotImplementedError("sorry, no detailed help yet for %r" % cmdname)
103
108
 
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
 
 
 
109
    outfile.write('usage: ' + command_usage(topic, cmdclass) + '\n')
 
110
 
 
111
    if cmdclass.aliases:
 
112
        outfile.write('aliases: ' + ', '.join(cmdclass.aliases) + '\n')
 
113
    
112
114
    outfile.write(doc)
113
115
    if doc[-1] != '\n':
114
116
        outfile.write('\n')
115
117
    
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
 
118
    help_on_option(cmdclass.takes_options, outfile = None)
 
119
 
 
120
 
 
121
def help_on_option(options, outfile = None):
 
122
    import commands
121
123
    
122
124
    if not options:
123
125
        return
128
130
    outfile.write('\noptions:\n')
129
131
    for on in options:
130
132
        l = '    --' + on
131
 
        for shortname, longname in SHORT_OPTIONS.items():
 
133
        for shortname, longname in commands.SHORT_OPTIONS.items():
132
134
            if longname == on:
133
135
                l += ', -' + shortname
134
136
                break
135
137
        outfile.write(l + '\n')
136
138
 
137
139
 
138
 
def help_commands(outfile=None):
 
140
def help_commands(outfile = None):
139
141
    """List all commands"""
140
 
    from bzrlib.commands import (builtin_command_names,
141
 
                                 plugin_command_names,
142
 
                                 get_cmd_object)
 
142
    import inspect
 
143
    import commands
143
144
 
144
145
    if outfile == None:
145
146
        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:
 
147
    
 
148
    accu = []
 
149
    for cmdname, cmdclass in commands.get_all_cmds():
 
150
        accu.append((cmdname, cmdclass))
 
151
    accu.sort()
 
152
    for cmdname, cmdclass in accu:
 
153
        if cmdclass.hidden:
156
154
            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
 
        
 
155
        outfile.write(command_usage(cmdname, cmdclass) + '\n')
 
156
        help = inspect.getdoc(cmdclass)
 
157
        if help:
 
158
            outfile.write("    " + help.split('\n', 1)[0] + '\n')
 
159
 
 
160
            
 
161