13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17
17
"""A collection of extra help information for using bzr.
66
59
:param section: Section in reference manual - see SECT_* identifiers.
68
61
# The detail is stored as the 'object' and the metadata as the info
69
info = (summary, section)
62
info=(summary,section)
70
63
super(HelpTopicRegistry, self).register(topic, detail, info=info)
72
65
def register_lazy(self, topic, module_name, member_name, summary,
135
128
return ''.join(out)
138
def _load_from_file(topic_name):
139
"""Load help from a file.
141
Topics are expected to be txt files in bzrlib.help_topics.
143
resource_name = osutils.pathjoin("en", "%s.txt" % (topic_name,))
144
return osutils.resource_string('bzrlib.help_topics', resource_name)
147
131
def _help_on_revisionspec(name):
148
132
"""Generate the help for revision specs."""
150
134
import bzrlib.revisionspec
154
"""Revision Identifiers
156
A revision identifier refers to a specific state of a branch's history. It
157
can be expressed in several ways. It can begin with a keyword to
158
unambiguously specify a given lookup type; some examples are 'last:1',
159
'before:yesterday' and 'submit:'.
161
Alternately, it can be given without a keyword, in which case it will be
162
checked as a revision number, a tag, a revision id, a date specification, or a
163
branch specification, in that order. For example, 'date:today' could be
164
written as simply 'today', though if you have a tag called 'today' that will
167
If 'REV1' and 'REV2' are revision identifiers, then 'REV1..REV2' denotes a
168
revision range. Examples: '3647..3649', 'date:yesterday..-1' and
169
'branch:/path/to/branch1/..branch:/branch2' (note that there are no quotes or
170
spaces around the '..').
172
Ranges are interpreted differently by different commands. To the "log" command,
173
a range is a sequence of log messages, but to the "diff" command, the range
174
denotes a change between revisions (and not a sequence of changes). In
175
addition, "log" considers a closed range whereas "diff" and "merge" consider it
176
to be open-ended, that is, they include one end but not the other. For example:
177
"bzr log -r 3647..3649" shows the messages of revisions 3647, 3648 and 3649,
178
while "bzr diff -r 3647..3649" includes the changes done in revisions 3648 and
181
The keywords used as revision selection methods are the following:
137
out.append("Revision Identifiers\n")
138
out.append("A revision, or a range bound, can be one of the following.\n")
184
details.append("\nIn addition, plugins can provide other keywords.")
185
details.append("\nA detailed description of each keyword is given below.\n")
140
details.append("\nFurther details are given below.\n")
187
142
# The help text is indented 4 spaces - this re cleans that up below
188
143
indent_re = re.compile(r'^ ', re.MULTILINE)
189
for prefix, i in bzrlib.revisionspec.revspec_registry.iteritems():
144
for i in bzrlib.revisionspec.SPEC_TYPES:
191
146
if doc == bzrlib.revisionspec.RevisionSpec.help_txt:
216
171
def add_string(proto, help, maxl, prefix_width=20):
217
help_lines = textwrap.wrap(help, maxl - prefix_width,
218
break_long_words=False)
172
help_lines = textwrap.wrap(help, maxl - prefix_width)
219
173
line_with_indent = '\n' + ' ' * prefix_width
220
174
help_text = line_with_indent.join(help_lines)
221
175
return "%-20s%s\n" % (proto, help_text)
252
206
out += "\nSupported modifiers::\n\n " + \
256
\nBazaar supports all of the standard parts within the URL::
258
<protocol>://[user[:password]@]host[:port]/[path]
260
allowing URLs such as::
262
http://bzruser:BadPass@bzr.example.com:8080/bzr/trunk
264
For bzr+ssh:// and sftp:// URLs, Bazaar also supports paths that begin
265
with '~' as meaning that the rest of the path should be interpreted
266
relative to the remote user's home directory. For example if the user
267
``remote`` has a home directory of ``/home/remote`` on the server
268
shell.example.com, then::
270
bzr+ssh://remote@shell.example.com/~/myproject/trunk
272
would refer to ``/home/remote/myproject/trunk``.
274
Many commands that accept URLs also accept location aliases too.
275
See :doc:`location-alias-help` and :doc:`url-special-chars-help`.
282
"""Bazaar %s -- a free distributed version-control tool
283
http://bazaar.canonical.com/
213
"""Bazaar -- a free distributed version-control tool
214
http://bazaar-vcs.org/
286
217
bzr init makes this directory a versioned branch
303
233
bzr help init more help on e.g. init command
304
234
bzr help commands list all commands
305
235
bzr help topics list all help topics
306
""" % bzrlib.__version__
309
239
_global_options = \
310
240
"""Global Options
312
242
These options may be used with any command, and may appear in front of any
313
command. (e.g. ``bzr --profile help``).
243
command. (e.g. "bzr --profile help").
315
245
--version Print the version number. Must be supplied before the command.
316
246
--no-aliases Do not process command aliases when running this command.
317
247
--builtin Use the built-in version of a command, not the plugin version.
318
248
This does not suppress other plugin effects.
319
249
--no-plugins Do not process any plugins.
320
--no-l10n Do not translate messages.
321
--concurrency Number of processes that can be run concurrently (selftest).
323
251
--profile Profile execution using the hotshot profiler.
324
252
--lsprof Profile execution using the lsprof profiler.
328
256
"callgrind.out" or end with ".callgrind", the output will be
329
257
formatted for use with KCacheGrind. Otherwise, the output
330
258
will be a pickle.
331
--coverage Generate line coverage report in the specified directory.
333
See http://doc.bazaar.canonical.com/developers/profiling.html for more
334
information on profiling.
260
See doc/developers/profiling.txt for more information on profiling.
336
261
A number of debug flags are also available to assist troubleshooting and
337
development. See :doc:`debug-flags-help`.
264
-Dauth Trace authentication sections used.
265
-Derror Instead of normal error handling, always print a traceback on
267
-Devil Capture call sites that do expensive or badly-scaling
269
-Dhashcache Log every time a working file is read to determine its hash.
270
-Dhooks Trace hook execution.
271
-Dhttp Trace http connections, requests and responses
272
-Dhpss Trace smart protocol requests and responses.
273
-Dindex Trace major index operations.
274
-Dlock Trace when lockdir locks are taken or released.
340
277
_standard_options = \
341
278
"""Standard Options
343
280
Standard options are legal for all commands.
345
282
--help, -h Show help message.
346
283
--verbose, -v Display more information.
347
284
--quiet, -q Only display errors and warnings.
392
329
Lightweight checkouts work best when you have fast reliable access to the
393
330
master branch. This means that if the master branch is on the same disk or LAN
394
331
a lightweight checkout will be faster than a heavyweight one for any commands
395
that modify the revision history (as only one copy of the branch needs to
396
be updated). Heavyweight checkouts will generally be faster for any command
397
that uses the history but does not change it, but if the master branch is on
398
the same disk then there won't be a noticeable difference.
332
that modify the revision history (as only one copy branch needs to be updated).
333
Heavyweight checkouts will generally be faster for any command that uses the
334
history but does not change it, but if the master branch is on the same disk
335
then there wont be a noticeable difference.
400
337
Another possible use for a checkout is to use it with a treeless repository
401
338
containing your branches, where you maintain only one working tree by
402
switching the master branch that the checkout points to when you want to
339
switching the master branch that the checkout points to when you want to
403
340
work on a different branch.
405
342
Obviously to commit on a checkout you need to be able to write to the master
408
345
end. Checkouts also work on the local file system, so that all that matters is
409
346
file permissions.
411
You can change the master of a checkout by using the "switch" command (see
412
"help switch"). This will change the location that the commits are sent to.
413
The "bind" command can also be used to turn a normal branch into a heavy
414
checkout. If you would like to convert your heavy checkout into a normal
415
branch so that every commit is local, you can use the "unbind" command. To see
416
whether or not a branch is bound or not you can use the "info" command. If the
417
branch is bound it will tell you the location of the bound branch.
348
You can change the master of a checkout by using the "bind" command (see "help
349
bind"). This will change the location that the commits are sent to. The bind
350
command can also be used to turn a branch into a heavy checkout. If you
351
would like to convert your heavy checkout into a normal branch so that every
352
commit is local, you can use the "unbind" command.
419
354
Related commands::
423
358
update Pull any changes in the master branch in to your checkout
424
359
commit Make a commit that is sent to the master branch. If you have
425
a heavy checkout then the --local option will commit to the
360
a heavy checkout then the --local option will commit to the
426
361
checkout without sending the commit to the master
427
switch Change the master branch that the commits in the checkout will
362
bind Change the master branch that the commits in the checkout will
429
bind Turn a standalone branch into a heavy checkout so that any
430
commits will be sent to the master branch
431
364
unbind Turn a heavy checkout into a standalone branch so that any
432
365
commits are only made locally
433
info Displays whether a branch is bound or unbound. If the branch is
434
bound, then it will also display the location of the bound branch
437
368
_repositories = \
443
374
Repositories are a form of database. Bzr will usually maintain this for
444
375
good performance automatically, but in some situations (e.g. when doing
445
very many commits in a short time period) you may want to ask bzr to
376
very many commits in a short time period) you may want to ask bzr to
446
377
optimise the database indices. This can be done by the 'bzr pack' command.
448
379
By default just running 'bzr init' will create a repository within the new
527
458
branch history is stored), but multiple branches may share the same
528
459
repository (a shared repository). Branches can be copied and merged.
530
In addition, one branch may be bound to another one. Binding to another
531
branch indicates that commits which happen in this branch must also
532
happen in the other branch. Bazaar ensures consistency by not allowing
533
commits when the two branches are out of date. In order for a commit
534
to succeed, it may be necessary to update the current branch using
537
461
Related commands::
539
init Change a directory into a versioned branch.
540
branch Create a new branch that is a copy of an existing branch.
463
init Make a directory into a versioned branch.
464
branch Create a new copy of a branch.
541
465
merge Perform a three-way merge.
542
bind Bind a branch to another one.
593
515
_env_variables = \
594
516
"""Environment Variables
596
=================== ===========================================================
597
BZRPATH Path where bzr is to look for shell plugin external
599
BZR_EMAIL E-Mail address of the user. Overrides EMAIL.
600
EMAIL E-Mail address of the user.
601
BZR_EDITOR Editor for editing commit messages. Overrides EDITOR.
602
EDITOR Editor for editing commit messages.
603
BZR_PLUGIN_PATH Paths where bzr should look for plugins.
604
BZR_DISABLE_PLUGINS Plugins that bzr should not load.
605
BZR_PLUGINS_AT Plugins to load from a directory not in BZR_PLUGIN_PATH.
606
BZR_HOME Directory holding .bazaar config dir. Overrides HOME.
607
BZR_HOME (Win32) Directory holding bazaar config dir. Overrides APPDATA and
609
BZR_REMOTE_PATH Full name of remote 'bzr' command (for bzr+ssh:// URLs).
610
BZR_SSH Path to SSH client, or one of paramiko, openssh, sshcorp,
612
BZR_LOG Location of .bzr.log (use '/dev/null' to suppress log).
613
BZR_LOG (Win32) Location of .bzr.log (use 'NUL' to suppress log).
614
BZR_COLUMNS Override implicit terminal width.
615
BZR_CONCURRENCY Number of processes that can be run concurrently (selftest)
616
BZR_PROGRESS_BAR Override the progress display. Values are 'none', 'dots',
618
BZR_PDB Control whether to launch a debugger on error.
619
BZR_SIGQUIT_PDB Control whether SIGQUIT behaves normally or invokes a
621
=================== ===========================================================
518
================ =================================================================
519
BZRPATH Path where bzr is to look for shell plugin external commands.
520
BZR_EMAIL E-Mail address of the user. Overrides EMAIL.
521
EMAIL E-Mail address of the user.
522
BZR_EDITOR Editor for editing commit messages. Overrides EDITOR.
523
EDITOR Editor for editing commit messages.
524
BZR_PLUGIN_PATH Paths where bzr should look for plugins.
525
BZR_HOME Directory holding .bazaar config dir. Overrides HOME.
526
BZR_HOME (Win32) Directory holding bazaar config dir. Overrides APPDATA and HOME.
527
BZR_REMOTE_PATH Full name of remote 'bzr' command (for bzr+ssh:// URLs).
528
================ =================================================================
628
:On Unix: ~/.bazaar/bazaar.conf
535
:On Linux: ~/.bazaar/bazaar.conf
629
536
:On Windows: C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf
631
538
Contains the user's default configuration. The section ``[DEFAULT]`` is
649
555
A criss-cross in the branch history can cause the default merge technique
650
556
to emit more conflicts than would normally be expected.
652
In complex merge cases, ``bzr merge --lca`` or ``bzr merge --weave`` may give
653
better results. You may wish to ``bzr revert`` the working tree and merge
654
again. Alternatively, use ``bzr remerge`` on particular conflicted files.
558
If you encounter criss-crosses, you can use merge --weave instead, which
559
should provide a much better result.
656
561
Criss-crosses occur in a branch's history if two branches merge the same thing
657
562
and then merge one another, or if two branches merge one another at the same
672
577
The ``weave`` merge type is not affected by this problem because it uses
673
578
line-origin detection instead of a basis revision to determine the cause of
677
_branches_out_of_sync = """Branches Out of Sync
679
When reconfiguring a checkout, tree or branch into a lightweight checkout,
680
a local branch must be destroyed. (For checkouts, this is the local branch
681
that serves primarily as a cache.) If the branch-to-be-destroyed does not
682
have the same last revision as the new reference branch for the lightweight
683
checkout, data could be lost, so Bazaar refuses.
685
How you deal with this depends on *why* the branches are out of sync.
687
If you have a checkout and have done local commits, you can get back in sync
688
by running "bzr update" (and possibly "bzr commit").
690
If you have a branch and the remote branch is out-of-date, you can push
691
the local changes using "bzr push". If the local branch is out of date, you
692
can do "bzr pull". If both branches have had changes, you can merge, commit
693
and then push your changes. If you decide that some of the changes aren't
694
useful, you can "push --overwrite" or "pull --overwrite" instead.
701
To ensure that older clients do not access data incorrectly,
702
Bazaar's policy is to introduce a new storage format whenever
703
new features requiring new metadata are added. New storage
704
formats may also be introduced to improve performance and
707
The newest format, 2a, is highly recommended. If your
708
project is not using 2a, then you should suggest to the
709
project owner to upgrade.
714
Some of the older formats have two variants:
715
a plain one and a rich-root one. The latter include an additional
716
field about the root of the tree. There is no performance cost
717
for using a rich-root format but you cannot easily merge changes
718
from a rich-root format into a plain format. As a consequence,
719
moving a project to a rich-root format takes some co-ordination
720
in that all contributors need to upgrade their repositories
721
around the same time. 2a and all future formats will be
722
implicitly rich-root.
724
See :doc:`current-formats-help` for the complete list of
725
currently supported formats. See :doc:`other-formats-help` for
726
descriptions of any available experimental and deprecated formats.
730
582
# Register help topics
732
584
"Explain how to use --revision")
733
585
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
734
586
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
735
def get_current_formats_topic(topic):
736
from bzrlib import bzrdir
737
return "Current Storage Formats\n\n" + \
738
bzrdir.format_registry.help_topic(topic)
739
def get_other_formats_topic(topic):
740
from bzrlib import bzrdir
741
return "Other Storage Formats\n\n" + \
742
bzrdir.format_registry.help_topic(topic)
743
topic_registry.register('current-formats', get_current_formats_topic,
744
'Current storage formats')
745
topic_registry.register('other-formats', get_other_formats_topic,
746
'Experimental and deprecated storage formats')
587
def get_format_topic(topic):
588
from bzrlib import bzrdir
589
return "Storage Formats\n\n" + bzrdir.format_registry.help_topic(topic)
590
topic_registry.register('formats', get_format_topic, 'Directory formats')
747
591
topic_registry.register('standard-options', _standard_options,
748
592
'Options that can be used with any command')
749
593
topic_registry.register('global-options', _global_options,
754
598
"Help on status flags")
755
599
def get_bugs_topic(topic):
756
600
from bzrlib import bugtracker
757
return ("Bug Tracker Settings\n\n" +
758
bugtracker.tracker_registry.help_topic(topic))
759
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker settings')
601
return "Bug Trackers\n\n" + bugtracker.tracker_registry.help_topic(topic)
602
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker support')
760
603
topic_registry.register('env-variables', _env_variables,
761
604
'Environment variable names and values')
762
605
topic_registry.register('files', _files,
763
606
'Information on configuration and log files')
764
topic_registry.register_lazy('hooks', 'bzrlib.hooks', 'hooks_help_text',
765
'Points at which custom processing can be added')
767
# Load some of the help topics from files. Note that topics which reproduce API
768
# details will tend to skew (quickly usually!) so please seek other solutions
770
topic_registry.register('authentication', _load_from_file,
771
'Information on configuring authentication')
772
topic_registry.register('configuration', _load_from_file,
773
'Details on the configuration settings available')
774
topic_registry.register('conflict-types', _load_from_file,
775
'Types of conflicts and what to do about them')
776
topic_registry.register('debug-flags', _load_from_file,
777
'Options to show or record debug information')
778
topic_registry.register('location-alias', _load_from_file,
779
'Aliases for remembered locations')
780
topic_registry.register('log-formats', _load_from_file,
781
'Details on the logging formats available')
782
topic_registry.register('url-special-chars', _load_from_file,
783
'Special character handling in URLs')
786
609
# Register concept topics.
791
614
'Information on what a branch is', SECT_CONCEPT)
792
615
topic_registry.register('checkouts', _checkouts,
793
616
'Information on what a checkout is', SECT_CONCEPT)
794
topic_registry.register('content-filters', _load_from_file,
795
'Conversion of content into/from working trees',
797
topic_registry.register('diverged-branches', _load_from_file,
798
'How to fix diverged branches',
800
topic_registry.register('eol', _load_from_file,
801
'Information on end-of-line handling',
803
topic_registry.register('formats', _storage_formats,
804
'Information on choosing a storage format',
806
topic_registry.register('patterns', _load_from_file,
807
'Information on the pattern syntax',
809
617
topic_registry.register('repositories', _repositories,
810
618
'Basic information on shared repositories.',
812
topic_registry.register('rules', _load_from_file,
813
'Information on defining rule-based preferences',
815
620
topic_registry.register('standalone-trees', _standalone_trees,
816
621
'Information on what a standalone tree is',
819
624
'Information on working trees', SECT_CONCEPT)
820
625
topic_registry.register('criss-cross', _criss_cross,
821
626
'Information on criss-cross merging', SECT_CONCEPT)
822
topic_registry.register('sync-for-reconfigure', _branches_out_of_sync,
823
'Steps to resolve "out-of-sync" when reconfiguring',
827
629
class HelpTopicIndex(object):
877
670
returned instead of plain text.
879
672
result = topic_registry.get_detail(self.topic)
880
result += _format_see_also(additional_see_also)
673
# there is code duplicated here and in bzrlib/plugin.py's
674
# matching Topic code. This should probably be factored in
675
# to a helper function and a common base class.
676
if additional_see_also is not None:
677
see_also = sorted(set(additional_see_also))
681
result += '\n:See also: '
682
result += ', '.join(see_also)
882
685
result = help_as_plain_text(result)
900
700
elif line.endswith('::'):
902
# Map :doc:`xxx-help` to ``bzr help xxx``
903
line = re.sub(":doc:`(.+?)-help`", r'``bzr help \1``', line)
904
702
result.append(line)
905
703
return "\n".join(result) + "\n"
908
class ConfigOptionHelpIndex(object):
909
"""A help index that returns help topics for config options."""
912
self.prefix = 'configuration/'
914
def get_topics(self, topic):
915
"""Search for topic in the registered config options.
917
:param topic: A topic to search for.
918
:return: A list which is either empty or contains a single
923
elif topic.startswith(self.prefix):
924
topic = topic[len(self.prefix):]
925
if topic in config.option_registry:
926
return [config.option_registry.get(topic)]
added
removed
bzrlib/help_topics.py
