← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics.py

Merge bzr.dev.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics.py
81
81
 
82
82
 
83
83
def _help_on_revisionspec(name):
84
 
    """"Write the summary help for all documented topics to outfile."""
 
84
    """Write the summary help for all documented topics to outfile."""
85
85
    import bzrlib.revisionspec
86
86
 
87
87
    out = []
100
100
    return ''.join(out)
101
101
 
102
102
 
 
103
def _help_on_transport(name):
 
104
    from bzrlib.transport import (
 
105
        transport_list_registry,
 
106
    )
 
107
    import textwrap
 
108
 
 
109
    def add_string(proto, help, maxl, prefix_width=20):
 
110
       help_lines = textwrap.wrap(help, maxl - prefix_width)
 
111
       line_with_indent = '\n' + ' ' * prefix_width
 
112
       help_text = line_with_indent.join(help_lines)
 
113
       return "%-20s%s\n" % (proto, help_text)
 
114
 
 
115
    def sort_func(a,b):
 
116
        a1 = a[:a.rfind("://")]
 
117
        b1 = b[:b.rfind("://")]
 
118
        if a1>b1:
 
119
            return +1
 
120
        elif a1<b1:
 
121
            return -1
 
122
        else:
 
123
            return 0
 
124
 
 
125
    out = []
 
126
    protl = []
 
127
    decl = []
 
128
    protos = transport_list_registry.keys( )
 
129
    protos.sort(sort_func)
 
130
    for proto in protos:
 
131
        shorthelp = transport_list_registry.get_help(proto)
 
132
        if not shorthelp:
 
133
            continue
 
134
        if proto.endswith("://"):
 
135
            protl.extend(add_string(proto, shorthelp, 79))
 
136
        else:
 
137
            decl.extend(add_string(proto, shorthelp, 79))
 
138
 
 
139
 
 
140
    out = "\nSupported URL prefix\n--------------------\n" + \
 
141
            ''.join(protl)
 
142
 
 
143
    if len(decl):
 
144
        out += "\nSupported modifiers\n-------------------\n" + \
 
145
            ''.join(decl)
 
146
 
 
147
    return out
 
148
 
 
149
 
103
150
_basic_help= \
104
151
"""Bazaar -- a free distributed version-control tool
105
152
http://bazaar-vcs.org/
106
153
 
107
154
Basic commands:
108
 
 
109
155
  bzr init           makes this directory a versioned branch
110
156
  bzr branch         make a copy of another branch
111
157
 
128
174
"""
129
175
 
130
176
 
 
177
_global_options =\
 
178
"""Global Options
 
179
 
 
180
These options may be used with any command, and may appear in front of any
 
181
command.  (e.g. "bzr --quiet help").
 
182
 
 
183
--quiet        Suppress informational output; only print errors and warnings
 
184
--version      Print the version number
 
185
 
 
186
--no-aliases   Do not process command aliases when running this command
 
187
--builtin      Use the built-in version of a command, not the plugin version.
 
188
               This does not suppress other plugin effects
 
189
--no-plugins   Do not process any plugins
 
190
 
 
191
-Derror        Instead of normal error handling, always print a traceback on
 
192
               error.
 
193
--profile      Profile execution using the hotshot profiler
 
194
--lsprof       Profile execution using the lsprof profiler
 
195
--lsprof-file  Profile execution using the lsprof profiler, and write the
 
196
               results to a specified file.
 
197
 
 
198
Note: --version must be supplied before any command.
 
199
"""
 
200
 
 
201
_checkouts = \
 
202
"""Checkouts
 
203
 
 
204
Checkouts are source trees that are connected to a branch, so that when
 
205
you commit in the source tree, the commit goes into that branch.  They
 
206
allow you to use a simpler, more centralized workflow, ignoring some of
 
207
Bazaar's decentralized features until you want them. Using checkouts
 
208
with shared repositories is very similar to working with SVN or CVS, but
 
209
doesn't have the same restrictions.  And using checkouts still allows
 
210
others working on the project to use whatever workflow they like.
 
211
 
 
212
A checkout is created with the bzr checkout command (see "help checkout").
 
213
You pass it a reference to another branch, and it will create a local copy
 
214
for you that still contains a reference to the branch you created the
 
215
checkout from (the master branch). Then if you make any commits they will be
 
216
made on the other branch first. This creates an instant mirror of your work, or
 
217
facilitates lockstep development, where each developer is working together,
 
218
continuously integrating the changes of others.
 
219
 
 
220
However the checkout is still a first class branch in Bazaar terms, so that
 
221
you have the full history locally.  As you have a first class branch you can
 
222
also commit locally if you want, for instance due to the temporary loss af a
 
223
network connection. Use the --local option to commit to do this. All the local
 
224
commits will then be made on the master branch the next time you do a non-local
 
225
commit.
 
226
 
 
227
If you are using a checkout from a shared branch you will periodically want to
 
228
pull in all the changes made by others. This is done using the "update"
 
229
command. The changes need to be applied before any non-local commit, but
 
230
Bazaar will tell you if there are any changes and suggest that you use this
 
231
command when needed.
 
232
 
 
233
It is also possible to create a "lightweight" checkout by passing the
 
234
--lightweight flag to checkout. A lightweight checkout is even closer to an
 
235
SVN checkout in that it is not a first class branch, it mainly consists of the
 
236
working tree. This means that any history operations must query the master
 
237
branch, which could be slow if a network connection is involved. Also, as you
 
238
don't have a local branch, then you cannot commit locally.
 
239
 
 
240
Lightweight checkouts work best when you have fast reliable access to the
 
241
master branch. This means that if the master branch is on the same disk or LAN
 
242
a lightweight checkout will be faster than a heavyweight one for any commands
 
243
that modify the revision history (as only one copy branch needs to be updated).
 
244
Heavyweight checkouts will generally be faster for any command that uses the
 
245
history but does not change it, but if the master branch is on the same disk
 
246
then there wont be a noticeable difference.
 
247
 
 
248
Another possible use for a checkout is to use it with a treeless repository
 
249
containing your branches, where you maintain only one working tree by
 
250
switching the master branch that the checkout points to when you want to 
 
251
work on a different branch.
 
252
 
 
253
Obviously to commit on a checkout you need to be able to write to the master
 
254
branch. This means that the master branch must be accessible over a writeable
 
255
protocol , such as sftp://, and that you have write permissions at the other
 
256
end. Checkouts also work on the local file system, so that all that matters is
 
257
file permissions.
 
258
 
 
259
You can change the master of a checkout by using the "bind" command (see "help
 
260
bind"). This will change the location that the commits are sent to. The bind
 
261
command can also be used to turn a branch into a heavy checkout. If you
 
262
would like to convert your heavy checkout into a normal branch so that every
 
263
commit is local, you can use the "unbind" command.
 
264
 
 
265
Related commands:
 
266
 
 
267
  checkout    Create a checkout. Pass --lightweight to get a lightweight
 
268
              checkout
 
269
  update      Pull any changes in the master branch in to your checkout
 
270
  commit      Make a commit that is sent to the master branch. If you have
 
271
              a heavy checkout then the --local option will commit to the 
 
272
              checkout without sending the commit to the master
 
273
  bind        Change the master branch that the commits in the checkout will
 
274
              be sent to
 
275
  unbind      Turn a heavy checkout into a standalone branch so that any
 
276
              commits are only made locally
 
277
"""
 
278
 
 
279
 
131
280
topic_registry.register("revisionspec", _help_on_revisionspec,
132
281
                        "Explain how to use --revision")
133
282
topic_registry.register('basic', _basic_help, "Basic commands")
134
283
topic_registry.register('topics', _help_on_topics, "Topics list")
 
284
def get_format_topic(topic):
 
285
    from bzrlib import bzrdir
 
286
    return bzrdir.format_registry.help_topic(topic)
 
287
topic_registry.register('formats', get_format_topic, 'Directory formats')
 
288
topic_registry.register('global-options', _global_options,
 
289
                        'Options that can be used with any command')
 
290
topic_registry.register('checkouts', _checkouts,
 
291
                        'Information on what a checkout is')
 
292
topic_registry.register('urlspec', _help_on_transport,
 
293
                        "Supported transport protocols")
 
294
def get_bugs_topic(topic):
 
295
    from bzrlib import bugtracker
 
296
    return bugtracker.tracker_registry.help_topic(topic)
 
297
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker support')
 
298
 
 
299
 
 
300
class HelpTopicIndex(object):
 
301
    """A index for bzr help that returns topics."""
 
302
 
 
303
    def __init__(self):
 
304
        self.prefix = ''
 
305
 
 
306
    def get_topics(self, topic):
 
307
        """Search for topic in the HelpTopicRegistry.
 
308
 
 
309
        :param topic: A topic to search for. None is treated as 'basic'.
 
310
        :return: A list which is either empty or contains a single
 
311
            RegisteredTopic entry.
 
312
        """
 
313
        if topic is None:
 
314
            topic = 'basic'
 
315
        if topic in topic_registry:
 
316
            return [RegisteredTopic(topic)]
 
317
        else:
 
318
            return []
 
319
 
 
320
 
 
321
class RegisteredTopic(object):
 
322
    """A help topic which has been registered in the HelpTopicRegistry.
 
323
 
 
324
    These topics consist of nothing more than the name of the topic - all
 
325
    data is retrieved on demand from the registry.
 
326
    """
 
327
 
 
328
    def __init__(self, topic):
 
329
        """Constructor.
 
330
 
 
331
        :param topic: The name of the topic that this represents.
 
332
        """
 
333
        self.topic = topic
 
334
 
 
335
    def get_help_text(self, additional_see_also=None):
 
336
        """Return a string with the help for this topic.
 
337
 
 
338
        :param additional_see_also: Additional help topics to be
 
339
            cross-referenced.
 
340
        """
 
341
        result = topic_registry.get_detail(self.topic)
 
342
        # there is code duplicated here and in bzrlib/plugin.py's 
 
343
        # matching Topic code. This should probably be factored in
 
344
        # to a helper function and a common base class.
 
345
        if additional_see_also is not None:
 
346
            see_also = sorted(set(additional_see_also))
 
347
        else:
 
348
            see_also = None
 
349
        if see_also:
 
350
            result += '\nSee also: '
 
351
            result += ', '.join(see_also)
 
352
            result += '\n'
 
353
        return result
 
354
 
 
355
    def get_help_topic(self):
 
356
        """Return the help topic this can be found under."""
 
357
        return self.topic