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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
17
"""A collection of extra help information for using bzr.
153
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'
155
A revision identifier refers to a specific state of a branch's history. It
156
can be expressed in several ways. It can begin with a keyword to
157
unambiguously specify a given lookup type; some examples are 'last:1',
158
'before:yesterday' and 'submit:'.
160
Alternately, it can be given without a keyword, in which case it will be
161
checked as a revision number, a tag, a revision id, a date specification, or a
162
branch specification, in that order. For example, 'date:today' could be
163
written as simply 'today', though if you have a tag called 'today' that will
160
166
If 'REV1' and 'REV2' are revision identifiers, then 'REV1..REV2' denotes a
161
167
revision range. Examples: '3647..3649', 'date:yesterday..-1' and
168
174
addition, "log" considers a closed range whereas "diff" and "merge" consider it
169
175
to be open-ended, that is, they include one end but not the other. For example:
170
176
"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
177
while "bzr diff -r 3647..3649" includes the changes done in revisions 3648 and
174
180
The keywords used as revision selection methods are the following:
209
215
def add_string(proto, help, maxl, prefix_width=20):
210
help_lines = textwrap.wrap(help, maxl - prefix_width)
216
help_lines = textwrap.wrap(help, maxl - prefix_width,
217
break_long_words=False)
211
218
line_with_indent = '\n' + ' ' * prefix_width
212
219
help_text = line_with_indent.join(help_lines)
213
220
return "%-20s%s\n" % (proto, help_text)
244
251
out += "\nSupported modifiers::\n\n " + \
255
\nBazaar supports all of the standard parts within the URL::
257
<protocol>://[user[:password]@]host[:port]/[path]
259
allowing URLs such as::
261
http://bzruser:BadPass@bzr.example.com:8080/bzr/trunk
263
For bzr+ssh:// and sftp:// URLs, Bazaar also supports paths that begin
264
with '~' as meaning that the rest of the path should be interpreted
265
relative to the remote user's home directory. For example if the user
266
``remote`` has a home directory of ``/home/remote`` on the server
267
shell.example.com, then::
269
bzr+ssh://remote@shell.example.com/~/myproject/trunk
271
would refer to ``/home/remote/myproject/trunk``.
273
Many commands that accept URLs also accept location aliases too. See
274
::doc:`location-alias-help`.
251
"""Bazaar -- a free distributed version-control tool
252
http://bazaar-vcs.org/
281
"""Bazaar %s -- a free distributed version-control tool
282
http://www.bazaar.canonical.com/
255
285
bzr init makes this directory a versioned branch
271
302
bzr help init more help on e.g. init command
272
303
bzr help commands list all commands
273
304
bzr help topics list all help topics
305
""" % bzrlib.__version__
277
308
_global_options = \
278
309
"""Global Options
280
311
These options may be used with any command, and may appear in front of any
281
command. (e.g. "bzr --profile help").
312
command. (e.g. ``bzr --profile help``).
283
314
--version Print the version number. Must be supplied before the command.
284
315
--no-aliases Do not process command aliases when running this command.
285
316
--builtin Use the built-in version of a command, not the plugin version.
286
317
This does not suppress other plugin effects.
287
318
--no-plugins Do not process any plugins.
319
--concurrency Number of processes that can be run concurrently (selftest).
289
321
--profile Profile execution using the hotshot profiler.
290
322
--lsprof Profile execution using the lsprof profiler.
296
328
will be a pickle.
297
329
--coverage Generate line coverage report in the specified directory.
299
See doc/developers/profiling.txt for more information on profiling.
331
See http://doc.bazaar.canonical.com/developers/profiling.html for more
332
information on profiling.
300
334
A number of debug flags are also available to assist troubleshooting and
303
-Dauth Trace authentication sections used.
304
-Derror Instead of normal error handling, always print a traceback
306
-Devil Capture call sites that do expensive or badly-scaling
308
-Dfetch Trace history copying between repositories.
309
-Dhashcache Log every time a working file is read to determine its hash.
310
-Dhooks Trace hook execution.
311
-Dhpss Trace smart protocol requests and responses.
312
-Dhttp Trace http connections, requests and responses
313
-Dindex Trace major index operations.
314
-Dknit Trace knit operations.
315
-Dlock Trace when lockdir locks are taken or released.
316
-Dmerge Emit information for debugging merges.
317
-Dpack Emit information about pack operations.
335
development. See :doc:`debug-flags-help`.
320
338
_standard_options = \
321
339
"""Standard Options
323
341
Standard options are legal for all commands.
325
343
--help, -h Show help message.
326
344
--verbose, -v Display more information.
327
345
--quiet, -q Only display errors and warnings.
388
406
end. Checkouts also work on the local file system, so that all that matters is
389
407
file permissions.
391
You can change the master of a checkout by using the "bind" command (see "help
392
bind"). This will change the location that the commits are sent to. The bind
393
command can also be used to turn a branch into a heavy checkout. If you
394
would like to convert your heavy checkout into a normal branch so that every
395
commit is local, you can use the "unbind" command.
409
You can change the master of a checkout by using the "switch" command (see
410
"help switch"). This will change the location that the commits are sent to.
411
The "bind" command can also be used to turn a normal branch into a heavy
412
checkout. If you would like to convert your heavy checkout into a normal
413
branch so that every commit is local, you can use the "unbind" command. To see
414
whether or not a branch is bound or not you can use the "info" command. If the
415
branch is bound it will tell you the location of the bound branch.
397
417
Related commands::
401
421
update Pull any changes in the master branch in to your checkout
402
422
commit Make a commit that is sent to the master branch. If you have
403
a heavy checkout then the --local option will commit to the
423
a heavy checkout then the --local option will commit to the
404
424
checkout without sending the commit to the master
405
bind Change the master branch that the commits in the checkout will
425
switch Change the master branch that the commits in the checkout will
427
bind Turn a standalone branch into a heavy checkout so that any
428
commits will be sent to the master branch
407
429
unbind Turn a heavy checkout into a standalone branch so that any
408
430
commits are only made locally
431
info Displays whether a branch is bound or unbound. If the branch is
432
bound, then it will also display the location of the bound branch
411
435
_repositories = \
417
441
Repositories are a form of database. Bzr will usually maintain this for
418
442
good performance automatically, but in some situations (e.g. when doing
419
very many commits in a short time period) you may want to ask bzr to
443
very many commits in a short time period) you may want to ask bzr to
420
444
optimise the database indices. This can be done by the 'bzr pack' command.
422
446
By default just running 'bzr init' will create a repository within the new
501
525
branch history is stored), but multiple branches may share the same
502
526
repository (a shared repository). Branches can be copied and merged.
528
In addition, one branch may be bound to another one. Binding to another
529
branch indicates that commits which happen in this branch must also
530
happen in the other branch. Bazaar ensures consistency by not allowing
531
commits when the two branches are out of date. In order for a commit
532
to succeed, it may be necessary to update the current branch using
504
535
Related commands::
506
537
init Change a directory into a versioned branch.
507
branch Create a new copy of a branch.
538
branch Create a new branch that is a copy of an existing branch.
508
539
merge Perform a three-way merge.
540
bind Bind a branch to another one.
568
601
BZR_HOME Directory holding .bazaar config dir. Overrides HOME.
569
602
BZR_HOME (Win32) Directory holding bazaar config dir. Overrides APPDATA and HOME.
570
603
BZR_REMOTE_PATH Full name of remote 'bzr' command (for bzr+ssh:// URLs).
571
BZR_SSH SSH client: paramiko (default), openssh, ssh, plink.
604
BZR_SSH Path to SSH client, or one of paramiko, openssh, sshcorp, plink.
572
605
BZR_LOG Location of .bzr.log (use '/dev/null' to suppress log).
573
606
BZR_LOG (Win32) Location of .bzr.log (use 'NUL' to suppress log).
607
BZR_COLUMNS Override implicit terminal width.
608
BZR_CONCURRENCY Number of processes that can be run concurrently (selftest).
574
609
================ =================================================================
689
To ensure that older clients do not access data incorrectly,
690
Bazaar's policy is to introduce a new storage format whenever
691
new features requiring new metadata are added. New storage
692
formats may also be introduced to improve performance and
695
The newest format, 2a, is highly recommended. If your
696
project is not using 2a, then you should suggest to the
697
project owner to upgrade.
702
Some of the older formats have two variants:
703
a plain one and a rich-root one. The latter include an additional
704
field about the root of the tree. There is no performance cost
705
for using a rich-root format but you cannot easily merge changes
706
from a rich-root format into a plain format. As a consequence,
707
moving a project to a rich-root format takes some co-ordination
708
in that all contributors need to upgrade their repositories
709
around the same time. 2a and all future formats will be
710
implicitly rich-root.
712
See :doc:`current-formats-help` for the complete list of
713
currently supported formats. See :doc:`other-formats-help` for
714
descriptions of any available experimental and deprecated formats.
651
718
# Register help topics
652
719
topic_registry.register("revisionspec", _help_on_revisionspec,
653
720
"Explain how to use --revision")
654
721
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
655
722
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
656
def get_format_topic(topic):
657
from bzrlib import bzrdir
658
return "Storage Formats\n\n" + bzrdir.format_registry.help_topic(topic)
659
topic_registry.register('formats', get_format_topic, 'Directory formats')
723
def get_current_formats_topic(topic):
724
from bzrlib import bzrdir
725
return "Current Storage Formats\n\n" + \
726
bzrdir.format_registry.help_topic(topic)
727
def get_other_formats_topic(topic):
728
from bzrlib import bzrdir
729
return "Other Storage Formats\n\n" + \
730
bzrdir.format_registry.help_topic(topic)
731
topic_registry.register('current-formats', get_current_formats_topic,
732
'Current storage formats')
733
topic_registry.register('other-formats', get_other_formats_topic,
734
'Experimental and deprecated storage formats')
660
735
topic_registry.register('standard-options', _standard_options,
661
736
'Options that can be used with any command')
662
737
topic_registry.register('global-options', _global_options,
667
742
"Help on status flags")
668
743
def get_bugs_topic(topic):
669
744
from bzrlib import bugtracker
670
return ("Bug Tracker Settings\n\n" +
745
return ("Bug Tracker Settings\n\n" +
671
746
bugtracker.tracker_registry.help_topic(topic))
672
747
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker settings')
673
748
topic_registry.register('env-variables', _env_variables,
674
749
'Environment variable names and values')
675
750
topic_registry.register('files', _files,
676
751
'Information on configuration and log files')
752
topic_registry.register_lazy('hooks', 'bzrlib.hooks', 'hooks_help_text',
753
'Points at which custom processing can be added')
678
# Load some of the help topics from files
755
# Load some of the help topics from files. Note that topics which reproduce API
756
# details will tend to skew (quickly usually!) so please seek other solutions
679
758
topic_registry.register('authentication', _load_from_file,
680
759
'Information on configuring authentication')
681
760
topic_registry.register('configuration', _load_from_file,
682
761
'Details on the configuration settings available')
683
topic_registry.register('conflicts', _load_from_file,
762
topic_registry.register('conflict-types', _load_from_file,
684
763
'Types of conflicts and what to do about them')
685
topic_registry.register('hooks', _load_from_file,
686
'Points at which custom processing can be added')
764
topic_registry.register('debug-flags', _load_from_file,
765
'Options to show or record debug information')
766
topic_registry.register('location-alias', _load_from_file,
767
'Aliases for remembered locations')
768
topic_registry.register('log-formats', _load_from_file,
769
'Details on the logging formats available')
689
772
# Register concept topics.
694
777
'Information on what a branch is', SECT_CONCEPT)
695
778
topic_registry.register('checkouts', _checkouts,
696
779
'Information on what a checkout is', SECT_CONCEPT)
780
topic_registry.register('content-filters', _load_from_file,
781
'Conversion of content into/from working trees',
783
topic_registry.register('diverged-branches', _load_from_file,
784
'How to fix diverged branches',
786
topic_registry.register('eol', _load_from_file,
787
'Information on end-of-line handling',
789
topic_registry.register('formats', _storage_formats,
790
'Information on choosing a storage format',
697
792
topic_registry.register('patterns', _load_from_file,
698
793
'Information on the pattern syntax',
759
854
returned instead of plain text.
761
856
result = topic_registry.get_detail(self.topic)
762
# there is code duplicated here and in bzrlib/plugin.py's
857
# there is code duplicated here and in bzrlib/plugin.py's
763
858
# matching Topic code. This should probably be factored in
764
859
# to a helper function and a common base class.
765
860
if additional_see_also is not None:
added
removed
bzrlib/help_topics/__init__.py
