← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/__init__.py

  • Committer: Martin Pool
  • Date: 2009-03-24 05:21:02 UTC
  • mfrom: (4192 +trunk)
  • mto: This revision was merged to the branch mainline in revision 4202.
  • Revision ID: mbp@sourcefrog.net-20090324052102-8kk087b32tep3d9h
merge trunk

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics/__init__.py
1
 
# Copyright (C) 2006 Canonical Ltd
 
1
# Copyright (C) 2006, 2009 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
126
126
 
127
127
    topics = topic_registry.keys()
128
128
    lmax = max(len(topic) for topic in topics)
129
 
        
 
129
 
130
130
    out = []
131
131
    for topic in topics:
132
132
        summary = topic_registry.get_summary(topic)
149
149
    import bzrlib.revisionspec
150
150
 
151
151
    out = []
152
 
    out.append("Revision Identifiers\n")
153
 
    out.append("A revision, or a range bound, can be one of the following.\n")
 
152
    out.append(
 
153
"""Revision Identifiers
 
154
 
 
155
A revision identifier refers to a specific state of a branch's history. It can
 
156
be a revision number, or a keyword followed by ':' and often other
 
157
parameters. Some examples of identifiers are '3', 'last:1', 'before:yesterday'
 
158
and 'submit:'.
 
159
 
 
160
If 'REV1' and 'REV2' are revision identifiers, then 'REV1..REV2' denotes a
 
161
revision range. Examples: '3647..3649', 'date:yesterday..-1' and
 
162
'branch:/path/to/branch1/..branch:/branch2' (note that there are no quotes or
 
163
spaces around the '..').
 
164
 
 
165
Ranges are interpreted differently by different commands. To the "log" command,
 
166
a range is a sequence of log messages, but to the "diff" command, the range
 
167
denotes a change between revisions (and not a sequence of changes).  In
 
168
addition, "log" considers a closed range whereas "diff" and "merge" consider it
 
169
to be open-ended, that is, they include one end but not the other.  For example:
 
170
"bzr log -r 3647..3649" shows the messages of revisions 3647, 3648 and 3649,
 
171
while "bzr diff -r 3647..3649" includes the changes done in revisions 3648 and
 
172
3649, but not 3647.
 
173
 
 
174
The keywords used as revision selection methods are the following:
 
175
""")
154
176
    details = []
155
 
    details.append("\nFurther details are given below.\n")
 
177
    details.append("\nIn addition, plugins can provide other keywords.")
 
178
    details.append("\nA detailed description of each keyword is given below.\n")
156
179
 
157
180
    # The help text is indented 4 spaces - this re cleans that up below
158
181
    indent_re = re.compile(r'^    ', re.MULTILINE)
159
 
    for i in bzrlib.revisionspec.SPEC_TYPES:
 
182
    for prefix, i in bzrlib.revisionspec.revspec_registry.iteritems():
160
183
        doc = i.help_txt
161
184
        if doc == bzrlib.revisionspec.RevisionSpec.help_txt:
162
185
            summary = "N/A"
168
191
            #doc = indent_re.sub('', doc)
169
192
            while (doc[-2:] == '\n\n' or doc[-1:] == ' '):
170
193
                doc = doc[:-1]
171
 
        
 
194
 
172
195
        # Note: The leading : here are HACKs to get reStructuredText
173
196
        # 'field' formatting - we know that the prefix ends in a ':'.
174
197
        out.append(":%s\n\t%s" % (i.prefix, summary))
241
264
 
242
265
  bzr merge          pull in changes from another branch
243
266
  bzr commit         save some or all changes
 
267
  bzr send           send changes via email
244
268
 
245
269
  bzr log            show history of changes
246
270
  bzr check          validate storage
275
299
 
276
300
See doc/developers/profiling.txt for more information on profiling.
277
301
A number of debug flags are also available to assist troubleshooting and
278
 
development.
279
 
 
280
 
-Dauth            Trace authentication sections used.
281
 
-Derror           Instead of normal error handling, always print a traceback
282
 
                  on error.
283
 
-Devil            Capture call sites that do expensive or badly-scaling
284
 
                  operations.
285
 
-Dfetch           Trace history copying between repositories.
286
 
-Dhashcache       Log every time a working file is read to determine its hash.
287
 
-Dhooks           Trace hook execution.
288
 
-Dhpss            Trace smart protocol requests and responses.
289
 
-Dhttp            Trace http connections, requests and responses
290
 
-Dindex           Trace major index operations.
291
 
-Dknit            Trace knit operations.
292
 
-Dlock            Trace when lockdir locks are taken or released.
293
 
-Dmerge           Emit information for debugging merges.
294
 
-Dpack            Emit information about pack operations.
 
302
development.  See `bzr help debug-flags`.
295
303
"""
296
304
 
297
305
_standard_options = \
298
306
"""Standard Options
299
307
 
300
308
Standard options are legal for all commands.
301
 
      
 
309
 
302
310
--help, -h     Show help message.
303
311
--verbose, -v  Display more information.
304
312
--quiet, -q    Only display errors and warnings.
356
364
 
357
365
Another possible use for a checkout is to use it with a treeless repository
358
366
containing your branches, where you maintain only one working tree by
359
 
switching the master branch that the checkout points to when you want to 
 
367
switching the master branch that the checkout points to when you want to
360
368
work on a different branch.
361
369
 
362
370
Obviously to commit on a checkout you need to be able to write to the master
377
385
              checkout
378
386
  update      Pull any changes in the master branch in to your checkout
379
387
  commit      Make a commit that is sent to the master branch. If you have
380
 
              a heavy checkout then the --local option will commit to the 
 
388
              a heavy checkout then the --local option will commit to the
381
389
              checkout without sending the commit to the master
382
390
  bind        Change the master branch that the commits in the checkout will
383
391
              be sent to
393
401
 
394
402
Repositories are a form of database. Bzr will usually maintain this for
395
403
good performance automatically, but in some situations (e.g. when doing
396
 
very many commits in a short time period) you may want to ask bzr to 
 
404
very many commits in a short time period) you may want to ask bzr to
397
405
optimise the database indices. This can be done by the 'bzr pack' command.
398
406
 
399
407
By default just running 'bzr init' will create a repository within the new
480
488
 
481
489
Related commands::
482
490
 
483
 
  init    Make a directory into a versioned branch.
 
491
  init    Change a directory into a versioned branch.
484
492
  branch  Create a new copy of a branch.
485
493
  merge   Perform a three-way merge.
486
494
"""
516
524
  - File unversioned
517
525
  R File renamed
518
526
  ? File unknown
 
527
  X File nonexistent (and unknown to bzr)
519
528
  C File has conflicts
520
529
  P Entry for a pending merge (not a file)
521
530
 
625
634
"""
626
635
 
627
636
 
 
637
_storage_formats = \
 
638
"""Storage Formats
 
639
 
 
640
To ensure that older clients do not access data incorrectly,
 
641
Bazaar's policy is to introduce a new storage format whenever
 
642
new features requiring new metadata are added. New storage
 
643
formats may also be introduced to improve performance and
 
644
scalability.
 
645
 
 
646
Use the following guidelines to select a format (stopping
 
647
as soon as a condition is true):
 
648
 
 
649
* If you are working on an existing project, use whatever
 
650
  format that project is using. (Bazaar will do this for you
 
651
  by default).
 
652
 
 
653
* If you are using bzr-svn to interoperate with a Subversion
 
654
  repository, use 1.9-rich-root.
 
655
 
 
656
* If you are working on a project with big trees (5000+ paths)
 
657
  or deep history (5000+ revisions), use 1.9.
 
658
 
 
659
* Otherwise, use the default format - it is good enough for
 
660
  most projects.
 
661
 
 
662
If some of your developers are unable to use the most recent
 
663
version of Bazaar (due to distro package availability say), be
 
664
sure to adjust the guidelines above accordingly. For example,
 
665
you may need to select 1.6 instead of 1.9 if your project has
 
666
standardized on Bazaar 1.7.
 
667
 
 
668
Note: Many of the currently supported formats have two variants:
 
669
a plain one and a rich-root one. The latter include an additional
 
670
field about the root of the tree. There is no performance cost
 
671
for using a rich-root format but you cannot easily merge changes
 
672
from a rich-root format into a plain format. As a consequence,
 
673
moving a project to a rich-root format takes some co-ordination
 
674
in that all contributors need to upgrade their repositories
 
675
around the same time. (It is for this reason that we have delayed
 
676
making a rich-root format the default so far, though we will do
 
677
so at some appropriate time in the future.)
 
678
 
 
679
See ``bzr help current-formats`` for the complete list of
 
680
currently supported formats. See ``bzr help other-formats`` for
 
681
descriptions of any available experimental and deprecated formats.
 
682
"""
 
683
 
 
684
 
628
685
# Register help topics
629
686
topic_registry.register("revisionspec", _help_on_revisionspec,
630
687
                        "Explain how to use --revision")
631
688
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
632
689
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
633
 
def get_format_topic(topic):
634
 
    from bzrlib import bzrdir
635
 
    return "Storage Formats\n\n" + bzrdir.format_registry.help_topic(topic)
636
 
topic_registry.register('formats', get_format_topic, 'Directory formats')
 
690
def get_current_formats_topic(topic):
 
691
    from bzrlib import bzrdir
 
692
    return "Current Storage Formats\n\n" + \
 
693
        bzrdir.format_registry.help_topic(topic)
 
694
def get_other_formats_topic(topic):
 
695
    from bzrlib import bzrdir
 
696
    return "Other Storage Formats\n\n" + \
 
697
        bzrdir.format_registry.help_topic(topic)
 
698
topic_registry.register('current-formats', get_current_formats_topic,
 
699
    'Current storage formats')
 
700
topic_registry.register('other-formats', get_other_formats_topic,
 
701
    'Experimental and deprecated storage formats')
637
702
topic_registry.register('standard-options', _standard_options,
638
703
                        'Options that can be used with any command')
639
704
topic_registry.register('global-options', _global_options,
644
709
                        "Help on status flags")
645
710
def get_bugs_topic(topic):
646
711
    from bzrlib import bugtracker
647
 
    return ("Bug Tracker Settings\n\n" + 
 
712
    return ("Bug Tracker Settings\n\n" +
648
713
        bugtracker.tracker_registry.help_topic(topic))
649
714
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker settings')
650
715
topic_registry.register('env-variables', _env_variables,
651
716
                        'Environment variable names and values')
652
717
topic_registry.register('files', _files,
653
718
                        'Information on configuration and log files')
 
719
topic_registry.register_lazy('hooks', 'bzrlib.hooks', 'hooks_help_text',
 
720
                        'Points at which custom processing can be added')
654
721
 
655
 
# Load some of the help topics from files
 
722
# Load some of the help topics from files. Note that topics which reproduce API
 
723
# details will tend to skew (quickly usually!) so please seek other solutions
 
724
# for such things.
656
725
topic_registry.register('authentication', _load_from_file,
657
726
                        'Information on configuring authentication')
658
727
topic_registry.register('configuration', _load_from_file,
659
728
                        'Details on the configuration settings available')
660
729
topic_registry.register('conflicts', _load_from_file,
661
730
                        'Types of conflicts and what to do about them')
662
 
topic_registry.register('hooks', _load_from_file,
663
 
                        'Points at which custom processing can be added')
 
731
topic_registry.register('debug-flags', _load_from_file,
 
732
                        'Options to show or record debug information')
 
733
topic_registry.register('log-formats', _load_from_file,
 
734
                        'Details on the logging formats available')
664
735
 
665
736
 
666
737
# Register concept topics.
671
742
                        'Information on what a branch is', SECT_CONCEPT)
672
743
topic_registry.register('checkouts', _checkouts,
673
744
                        'Information on what a checkout is', SECT_CONCEPT)
 
745
topic_registry.register('content-filters', _load_from_file,
 
746
                        'Conversion of content into/from working trees',
 
747
                        SECT_CONCEPT)
 
748
topic_registry.register('formats', _storage_formats,
 
749
                        'Information on choosing a storage format',
 
750
                        SECT_CONCEPT)
 
751
topic_registry.register('patterns', _load_from_file,
 
752
                        'Information on the pattern syntax',
 
753
                        SECT_CONCEPT)
674
754
topic_registry.register('repositories', _repositories,
675
755
                        'Basic information on shared repositories.',
676
756
                        SECT_CONCEPT)
 
757
topic_registry.register('rules', _load_from_file,
 
758
                        'Information on defining rule-based preferences',
 
759
                        SECT_CONCEPT)
677
760
topic_registry.register('standalone-trees', _standalone_trees,
678
761
                        'Information on what a standalone tree is',
679
762
                        SECT_CONCEPT)
682
765
topic_registry.register('criss-cross', _criss_cross,
683
766
                        'Information on criss-cross merging', SECT_CONCEPT)
684
767
topic_registry.register('sync-for-reconfigure', _branches_out_of_sync,
685
 
                        'Information on criss-cross merging', SECT_CONCEPT)
 
768
                        'Steps to resolve "out-of-sync" when reconfiguring',
 
769
                        SECT_CONCEPT)
686
770
 
687
771
 
688
772
class HelpTopicIndex(object):
729
813
            returned instead of plain text.
730
814
        """
731
815
        result = topic_registry.get_detail(self.topic)
732
 
        # there is code duplicated here and in bzrlib/plugin.py's 
 
816
        # there is code duplicated here and in bzrlib/plugin.py's
733
817
        # matching Topic code. This should probably be factored in
734
818
        # to a helper function and a common base class.
735
819
        if additional_see_also is not None: