149
149
import bzrlib.revisionspec
152
out.append("Revision Identifiers\n")
153
out.append("A revision, or a range bound, can be one of the following.\n")
153
"""Revision Identifiers
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'
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 '..').
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 3647 and
174
The keywords used as revision selection methods are the following:
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")
157
180
# The help text is indented 4 spaces - this re cleans that up below
158
181
indent_re = re.compile(r'^ ', re.MULTILINE)
656
To ensure that older clients do not access data incorrectly,
657
Bazaar's policy is to introduce a new storage format whenever
658
new features requiring new metadata are added. New storage
659
formats may also be introduced to improve performance and
662
Use the following guidelines to select a format (stopping
663
as soon as a condition is true):
665
* If you are working on an existing project, use whatever
666
format that project is using. (Bazaar will do this for you
669
* If you are using bzr-svn to interoperate with a Subversion
670
repository, use 1.9-rich-root.
672
* If you are working on a project with big trees (5000+ paths)
673
or deep history (5000+ revisions), use 1.9.
675
* Otherwise, use the default format - it is good enough for
678
If some of your developers are unable to use the most recent
679
version of Bazaar (due to distro package availability say), be
680
sure to adjust the guidelines above accordingly. For example,
681
you may need to select 1.6 instead of 1.9 if your project has
682
standardized on Bazaar 1.7.
684
Note: Many of the currently supported formats have two variants:
685
a plain one and a rich-root one. The latter include an additional
686
field about the root of the tree. There is no performance cost
687
for using a rich-root format but you cannot easily merge changes
688
from a rich-root format into a plain format. As a consequence,
689
moving a project to a rich-root format takes some co-ordination
690
in that all contributors need to upgrade their repositories
691
around the same time. (It is for this reason that we have delayed
692
making a rich-root format the default so far, though we will do
693
so at some appropriate time in the future.)
695
See ``bzr help current-formats`` for the complete list of
696
currently supported formats. See ``bzr help other-formats`` for
697
descriptions of any available experimental and deprecated formats.
629
701
# Register help topics
630
702
topic_registry.register("revisionspec", _help_on_revisionspec,
631
703
"Explain how to use --revision")
632
704
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
633
705
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
634
def get_format_topic(topic):
635
from bzrlib import bzrdir
636
return "Storage Formats\n\n" + bzrdir.format_registry.help_topic(topic)
637
topic_registry.register('formats', get_format_topic, 'Directory formats')
706
def get_current_formats_topic(topic):
707
from bzrlib import bzrdir
708
return "Current Storage Formats\n\n" + \
709
bzrdir.format_registry.help_topic(topic)
710
def get_other_formats_topic(topic):
711
from bzrlib import bzrdir
712
return "Other Storage Formats\n\n" + \
713
bzrdir.format_registry.help_topic(topic)
714
topic_registry.register('current-formats', get_current_formats_topic,
715
'Current storage formats')
716
topic_registry.register('other-formats', get_other_formats_topic,
717
'Experimental and deprecated storage formats')
638
718
topic_registry.register('standard-options', _standard_options,
639
719
'Options that can be used with any command')
640
720
topic_registry.register('global-options', _global_options,
added
removed
bzrlib/help_topics/__init__.py
