151
149
import bzrlib.revisionspec
155
"""Revision Identifiers
157
A revision identifier refers to a specific state of a branch's history. It
158
can be expressed in several ways. It can begin with a keyword to
159
unambiguously specify a given lookup type; some examples are 'last:1',
160
'before:yesterday' and 'submit:'.
162
Alternately, it can be given without a keyword, in which case it will be
163
checked as a revision number, a tag, a revision id, a date specification, or a
164
branch specification, in that order. For example, 'date:today' could be
165
written as simply 'today', though if you have a tag called 'today' that will
168
If 'REV1' and 'REV2' are revision identifiers, then 'REV1..REV2' denotes a
169
revision range. Examples: '3647..3649', 'date:yesterday..-1' and
170
'branch:/path/to/branch1/..branch:/branch2' (note that there are no quotes or
171
spaces around the '..').
173
Ranges are interpreted differently by different commands. To the "log" command,
174
a range is a sequence of log messages, but to the "diff" command, the range
175
denotes a change between revisions (and not a sequence of changes). In
176
addition, "log" considers a closed range whereas "diff" and "merge" consider it
177
to be open-ended, that is, they include one end but not the other. For example:
178
"bzr log -r 3647..3649" shows the messages of revisions 3647, 3648 and 3649,
179
while "bzr diff -r 3647..3649" includes the changes done in revisions 3648 and
182
The keywords used as revision selection methods are the following:
152
out.append("Revision Identifiers\n")
153
out.append("A revision, or a range bound, can be one of the following.\n")
185
details.append("\nIn addition, plugins can provide other keywords.")
186
details.append("\nA detailed description of each keyword is given below.\n")
155
details.append("\nFurther details are given below.\n")
188
157
# The help text is indented 4 spaces - this re cleans that up below
189
158
indent_re = re.compile(r'^ ', re.MULTILINE)
190
for prefix, i in bzrlib.revisionspec.revspec_registry.iteritems():
159
for i in bzrlib.revisionspec.SPEC_TYPES:
192
161
if doc == bzrlib.revisionspec.RevisionSpec.help_txt:
253
221
out += "\nSupported modifiers::\n\n " + \
257
\nBazaar supports all of the standard parts within the URL::
259
<protocol>://[user[:password]@]host[:port]/[path]
261
allowing URLs such as::
263
http://bzruser:BadPass@bzr.example.com:8080/bzr/trunk
265
For bzr+ssh:// and sftp:// URLs, Bazaar also supports paths that begin
266
with '~' as meaning that the rest of the path should be interpreted
267
relative to the remote user's home directory. For example if the user
268
``remote`` has a home directory of ``/home/remote`` on the server
269
shell.example.com, then::
271
bzr+ssh://remote@shell.example.com/~/myproject/trunk
273
would refer to ``/home/remote/myproject/trunk``.
275
Many commands that accept URLs also accept location aliases too.
276
See :doc:`location-alias-help` and :doc:`url-special-chars-help`.
283
"""Bazaar %s -- a free distributed version-control tool
284
http://bazaar.canonical.com/
228
"""Bazaar -- a free distributed version-control tool
229
http://bazaar-vcs.org/
287
232
bzr init makes this directory a versioned branch
304
248
bzr help init more help on e.g. init command
305
249
bzr help commands list all commands
306
250
bzr help topics list all help topics
307
""" % bzrlib.__version__
310
254
_global_options = \
311
255
"""Global Options
313
257
These options may be used with any command, and may appear in front of any
314
command. (e.g. ``bzr --profile help``).
258
command. (e.g. "bzr --profile help").
316
260
--version Print the version number. Must be supplied before the command.
317
261
--no-aliases Do not process command aliases when running this command.
318
262
--builtin Use the built-in version of a command, not the plugin version.
319
263
This does not suppress other plugin effects.
320
264
--no-plugins Do not process any plugins.
321
--no-l10n Do not translate messages.
322
--concurrency Number of processes that can be run concurrently (selftest).
324
266
--profile Profile execution using the hotshot profiler.
325
267
--lsprof Profile execution using the lsprof profiler.
331
273
will be a pickle.
332
274
--coverage Generate line coverage report in the specified directory.
334
-Oname=value Override the ``name`` config option setting it to ``value`` for
335
the duration of the command. This can be used multiple times if
336
several options need to be overridden.
338
See http://doc.bazaar.canonical.com/developers/profiling.html for more
339
information on profiling.
276
See doc/developers/profiling.txt for more information on profiling.
341
277
A number of debug flags are also available to assist troubleshooting and
342
development. See :doc:`debug-flags-help`.
280
-Dauth Trace authentication sections used.
281
-Derror Instead of normal error handling, always print a traceback
283
-Devil Capture call sites that do expensive or badly-scaling
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.
345
297
_standard_options = \
346
298
"""Standard Options
348
300
Standard options are legal for all commands.
350
302
--help, -h Show help message.
351
303
--verbose, -v Display more information.
352
304
--quiet, -q Only display errors and warnings.
413
365
end. Checkouts also work on the local file system, so that all that matters is
414
366
file permissions.
416
You can change the master of a checkout by using the "switch" command (see
417
"help switch"). This will change the location that the commits are sent to.
418
The "bind" command can also be used to turn a normal branch into a heavy
419
checkout. If you would like to convert your heavy checkout into a normal
420
branch so that every commit is local, you can use the "unbind" command. To see
421
whether or not a branch is bound or not you can use the "info" command. If the
422
branch is bound it will tell you the location of the bound branch.
368
You can change the master of a checkout by using the "bind" command (see "help
369
bind"). This will change the location that the commits are sent to. The bind
370
command can also be used to turn a branch into a heavy checkout. If you
371
would like to convert your heavy checkout into a normal branch so that every
372
commit is local, you can use the "unbind" command.
424
374
Related commands::
428
378
update Pull any changes in the master branch in to your checkout
429
379
commit Make a commit that is sent to the master branch. If you have
430
a heavy checkout then the --local option will commit to the
380
a heavy checkout then the --local option will commit to the
431
381
checkout without sending the commit to the master
432
switch Change the master branch that the commits in the checkout will
382
bind Change the master branch that the commits in the checkout will
434
bind Turn a standalone branch into a heavy checkout so that any
435
commits will be sent to the master branch
436
384
unbind Turn a heavy checkout into a standalone branch so that any
437
385
commits are only made locally
438
info Displays whether a branch is bound or unbound. If the branch is
439
bound, then it will also display the location of the bound branch
442
388
_repositories = \
532
478
branch history is stored), but multiple branches may share the same
533
479
repository (a shared repository). Branches can be copied and merged.
535
In addition, one branch may be bound to another one. Binding to another
536
branch indicates that commits which happen in this branch must also
537
happen in the other branch. Bazaar ensures consistency by not allowing
538
commits when the two branches are out of date. In order for a commit
539
to succeed, it may be necessary to update the current branch using
542
481
Related commands::
544
483
init Change a directory into a versioned branch.
545
branch Create a new branch that is a copy of an existing branch.
484
branch Create a new copy of a branch.
546
485
merge Perform a three-way merge.
547
bind Bind a branch to another one.
598
known_env_variables = [
599
("BZRPATH", "Path where bzr is to look for shell plugin external commands."),
600
("BZR_EMAIL", "E-Mail address of the user. Overrides EMAIL."),
601
("EMAIL", "E-Mail address of the user."),
602
("BZR_EDITOR", "Editor for editing commit messages. Overrides EDITOR."),
603
("EDITOR", "Editor for editing commit messages."),
604
("BZR_PLUGIN_PATH", "Paths where bzr should look for plugins."),
605
("BZR_DISABLE_PLUGINS", "Plugins that bzr should not load."),
606
("BZR_PLUGINS_AT", "Plugins to load from a directory not in BZR_PLUGIN_PATH."),
607
("BZR_HOME", "Directory holding .bazaar config dir. Overrides HOME."),
608
("BZR_HOME (Win32)", "Directory holding bazaar config dir. Overrides APPDATA and HOME."),
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, plink or lsh."),
611
("BZR_LOG", "Location of .bzr.log (use '/dev/null' to suppress log)."),
612
("BZR_LOG (Win32)", "Location of .bzr.log (use 'NUL' to suppress log)."),
613
("BZR_COLUMNS", "Override implicit terminal width."),
614
("BZR_CONCURRENCY", "Number of processes that can be run concurrently (selftest)"),
615
("BZR_PROGRESS_BAR", "Override the progress display. Values are 'none' or 'text'."),
616
("BZR_PDB", "Control whether to launch a debugger on error."),
617
("BZR_SIGQUIT_PDB", "Control whether SIGQUIT behaves normally or invokes a breakin debugger."),
618
("BZR_TEXTUI_INPUT", "Force console input mode for prompts to line-based (instead of char-based)."),
621
def _env_variables(topic):
623
ret = ["Environment Variables\n\n"
624
"See bzr help configuration for more details.\n\n"]
625
max_key_len = max([len(k[0]) for k in known_env_variables])
626
desc_len = (80 - max_key_len - 2)
627
ret.append("=" * max_key_len + " " + "=" * desc_len + "\n")
628
for k, desc in known_env_variables:
629
ret.append(k + (max_key_len + 1 - len(k)) * " ")
630
ret.append("\n".join(textwrap.wrap(
631
desc, width=desc_len, subsequent_indent=" " * (max_key_len + 1))))
633
ret += "=" * max_key_len + " " + "=" * desc_len + "\n"
536
"""Environment Variables
538
================ =================================================================
539
BZRPATH Path where bzr is to look for shell plugin external commands.
540
BZR_EMAIL E-Mail address of the user. Overrides EMAIL.
541
EMAIL E-Mail address of the user.
542
BZR_EDITOR Editor for editing commit messages. Overrides EDITOR.
543
EDITOR Editor for editing commit messages.
544
BZR_PLUGIN_PATH Paths where bzr should look for plugins.
545
BZR_HOME Directory holding .bazaar config dir. Overrides HOME.
546
BZR_HOME (Win32) Directory holding bazaar config dir. Overrides APPDATA and HOME.
547
BZR_REMOTE_PATH Full name of remote 'bzr' command (for bzr+ssh:// URLs).
548
BZR_SSH SSH client: paramiko (default), openssh, ssh, plink.
549
BZR_LOG Location of .bzr.log (use '/dev/null' to suppress log).
550
BZR_LOG (Win32) Location of .bzr.log (use 'NUL' to suppress log).
551
================ =================================================================
639
:On Unix: ~/.bazaar/bazaar.conf
558
:On Linux: ~/.bazaar/bazaar.conf
640
559
:On Windows: C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf
642
561
Contains the user's default configuration. The section ``[DEFAULT]`` is
712
To ensure that older clients do not access data incorrectly,
713
Bazaar's policy is to introduce a new storage format whenever
714
new features requiring new metadata are added. New storage
715
formats may also be introduced to improve performance and
718
The newest format, 2a, is highly recommended. If your
719
project is not using 2a, then you should suggest to the
720
project owner to upgrade.
725
Some of the older formats have two variants:
726
a plain one and a rich-root one. The latter include an additional
727
field about the root of the tree. There is no performance cost
728
for using a rich-root format but you cannot easily merge changes
729
from a rich-root format into a plain format. As a consequence,
730
moving a project to a rich-root format takes some co-ordination
731
in that all contributors need to upgrade their repositories
732
around the same time. 2a and all future formats will be
733
implicitly rich-root.
735
See :doc:`current-formats-help` for the complete list of
736
currently supported formats. See :doc:`other-formats-help` for
737
descriptions of any available experimental and deprecated formats.
741
628
# Register help topics
742
629
topic_registry.register("revisionspec", _help_on_revisionspec,
743
630
"Explain how to use --revision")
744
631
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
745
632
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
746
def get_current_formats_topic(topic):
747
from bzrlib import controldir
748
return "Current Storage Formats\n\n" + \
749
controldir.format_registry.help_topic(topic)
750
def get_other_formats_topic(topic):
751
from bzrlib import controldir
752
return "Other Storage Formats\n\n" + \
753
controldir.format_registry.help_topic(topic)
754
topic_registry.register('current-formats', get_current_formats_topic,
755
'Current storage formats')
756
topic_registry.register('other-formats', get_other_formats_topic,
757
'Experimental and deprecated storage formats')
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')
758
637
topic_registry.register('standard-options', _standard_options,
759
638
'Options that can be used with any command')
760
639
topic_registry.register('global-options', _global_options,
765
644
"Help on status flags")
766
645
def get_bugs_topic(topic):
767
646
from bzrlib import bugtracker
768
return ("Bug Tracker Settings\n\n" +
647
return ("Bug Tracker Settings\n\n" +
769
648
bugtracker.tracker_registry.help_topic(topic))
770
649
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker settings')
771
650
topic_registry.register('env-variables', _env_variables,
772
651
'Environment variable names and values')
773
652
topic_registry.register('files', _files,
774
653
'Information on configuration and log files')
775
topic_registry.register_lazy('hooks', 'bzrlib.hooks', 'hooks_help_text',
776
'Points at which custom processing can be added')
777
topic_registry.register_lazy('location-alias', 'bzrlib.directory_service',
778
'AliasDirectory.help_text',
779
'Aliases for remembered locations')
781
# Load some of the help topics from files. Note that topics which reproduce API
782
# details will tend to skew (quickly usually!) so please seek other solutions
655
# Load some of the help topics from files
784
656
topic_registry.register('authentication', _load_from_file,
785
657
'Information on configuring authentication')
786
658
topic_registry.register('configuration', _load_from_file,
787
659
'Details on the configuration settings available')
788
topic_registry.register('conflict-types', _load_from_file,
660
topic_registry.register('conflicts', _load_from_file,
789
661
'Types of conflicts and what to do about them')
790
topic_registry.register('debug-flags', _load_from_file,
791
'Options to show or record debug information')
792
topic_registry.register('log-formats', _load_from_file,
793
'Details on the logging formats available')
794
topic_registry.register('url-special-chars', _load_from_file,
795
'Special character handling in URLs')
662
topic_registry.register('hooks', _load_from_file,
663
'Points at which custom processing can be added')
798
666
# Register concept topics.
803
671
'Information on what a branch is', SECT_CONCEPT)
804
672
topic_registry.register('checkouts', _checkouts,
805
673
'Information on what a checkout is', SECT_CONCEPT)
806
topic_registry.register('content-filters', _load_from_file,
807
'Conversion of content into/from working trees',
809
topic_registry.register('diverged-branches', _load_from_file,
810
'How to fix diverged branches',
812
topic_registry.register('eol', _load_from_file,
813
'Information on end-of-line handling',
815
topic_registry.register('formats', _storage_formats,
816
'Information on choosing a storage format',
818
674
topic_registry.register('patterns', _load_from_file,
819
675
'Information on the pattern syntax',
889
735
returned instead of plain text.
891
737
result = topic_registry.get_detail(self.topic)
892
result += _format_see_also(additional_see_also)
738
# there is code duplicated here and in bzrlib/plugin.py's
739
# matching Topic code. This should probably be factored in
740
# to a helper function and a common base class.
741
if additional_see_also is not None:
742
see_also = sorted(set(additional_see_also))
746
result += '\n:See also: '
747
result += ', '.join(see_also)
894
750
result = help_as_plain_text(result)
896
result = i18n.gettext_per_paragraph(result)
899
753
def get_help_topic(self):
914
765
elif line.endswith('::'):
916
# Map :doc:`xxx-help` to ``bzr help xxx``
917
line = re.sub(":doc:`(.+?)-help`", r'``bzr help \1``', line)
918
767
result.append(line)
919
768
return "\n".join(result) + "\n"
922
class ConfigOptionHelpIndex(object):
923
"""A help index that returns help topics for config options."""
926
self.prefix = 'configuration/'
928
def get_topics(self, topic):
929
"""Search for topic in the registered config options.
931
:param topic: A topic to search for.
932
:return: A list which is either empty or contains a single
937
elif topic.startswith(self.prefix):
938
topic = topic[len(self.prefix):]
939
if topic in config.option_registry:
940
return [config.option_registry.get(topic)]
added
removed
bzrlib/help_topics/__init__.py
