/breezy/unstable

To get this branch, use:
bzr branch https://code.breezy-vcs.org/breezy/unstable

« back to all changes in this revision

Viewing changes to breezy/help_topics/__init__.py

  • Committer: Jelmer Vernooij
  • Date: 2017-05-24 01:39:33 UTC
  • mfrom: (3815.3776.6)
  • Revision ID: jelmer@jelmer.uk-20170524013933-ir4y4tqtrsiz2ka2
New upstream snapshot.

Show diffs side-by-side

added added

removed removed

Lines of Context:
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
 
"""A collection of extra help information for using bzr.
 
17
"""A collection of extra help information for using brz.
18
18
 
19
19
Help topics are meant to be help for items that aren't commands, but will
20
 
help bzr become fully learnable without referring to a tutorial.
 
20
help brz become fully learnable without referring to a tutorial.
21
21
 
22
22
Limited formatting of help text is permitted to make the text useful
23
23
both within the reference manual (reStructuredText) and on the screen.
35
35
 
36
36
from __future__ import absolute_import
37
37
 
38
 
import bzrlib
39
 
from bzrlib import (
 
38
import breezy
 
39
from breezy import (
40
40
    config,
41
41
    osutils,
42
42
    registry,
139
139
def _load_from_file(topic_name):
140
140
    """Load help from a file.
141
141
 
142
 
    Topics are expected to be txt files in bzrlib.help_topics.
 
142
    Topics are expected to be txt files in breezy.help_topics.
143
143
    """
144
144
    resource_name = osutils.pathjoin("en", "%s.txt" % (topic_name,))
145
 
    return osutils.resource_string('bzrlib.help_topics', resource_name)
 
145
    return osutils.resource_string('breezy.help_topics', resource_name)
146
146
 
147
147
 
148
148
def _help_on_revisionspec(name):
149
149
    """Generate the help for revision specs."""
150
150
    import re
151
 
    import bzrlib.revisionspec
 
151
    import breezy.revisionspec
152
152
 
153
153
    out = []
154
154
    out.append(
175
175
denotes a change between revisions (and not a sequence of changes).  In
176
176
addition, "log" considers a closed range whereas "diff" and "merge" consider it
177
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
 
178
"brz log -r 3647..3649" shows the messages of revisions 3647, 3648 and 3649,
 
179
while "brz diff -r 3647..3649" includes the changes done in revisions 3648 and
180
180
3649, but not 3647.
181
181
 
182
182
The keywords used as revision selection methods are the following:
187
187
 
188
188
    # The help text is indented 4 spaces - this re cleans that up below
189
189
    indent_re = re.compile(r'^    ', re.MULTILINE)
190
 
    for prefix, i in bzrlib.revisionspec.revspec_registry.iteritems():
 
190
    for prefix, i in breezy.revisionspec.revspec_registry.iteritems():
191
191
        doc = i.help_txt
192
 
        if doc == bzrlib.revisionspec.RevisionSpec.help_txt:
 
192
        if doc == breezy.revisionspec.RevisionSpec.help_txt:
193
193
            summary = "N/A"
194
194
            doc = summary + "\n"
195
195
        else:
209
209
 
210
210
 
211
211
def _help_on_transport(name):
212
 
    from bzrlib.transport import (
 
212
    from breezy.transport import (
213
213
        transport_list_registry,
214
214
    )
215
215
    import textwrap
254
254
            '  '.join(decl)
255
255
 
256
256
    out += """\
257
 
\nBazaar supports all of the standard parts within the URL::
 
257
\nBreezy supports all of the standard parts within the URL::
258
258
 
259
259
  <protocol>://[user[:password]@]host[:port]/[path]
260
260
 
261
261
allowing URLs such as::
262
262
 
263
 
  http://bzruser:BadPass@bzr.example.com:8080/bzr/trunk
 
263
  http://brzuser:BadPass@brz.example.com:8080/brz/trunk
264
264
 
265
 
For bzr+ssh:// and sftp:// URLs, Bazaar also supports paths that begin
 
265
For brz+ssh:// and sftp:// URLs, Breezy also supports paths that begin
266
266
with '~' as meaning that the rest of the path should be interpreted
267
267
relative to the remote user's home directory.  For example if the user
268
268
``remote`` has a  home directory of ``/home/remote`` on the server
269
269
shell.example.com, then::
270
270
 
271
 
  bzr+ssh://remote@shell.example.com/~/myproject/trunk
 
271
  brz+ssh://remote@shell.example.com/~/myproject/trunk
272
272
 
273
273
would refer to ``/home/remote/myproject/trunk``.
274
274
 
280
280
 
281
281
 
282
282
_basic_help = \
283
 
"""Bazaar %s -- a free distributed version-control tool
 
283
"""Breezy %s -- a free distributed version-control tool
284
284
http://bazaar.canonical.com/
285
285
 
286
286
Basic commands:
287
 
  bzr init           makes this directory a versioned branch
288
 
  bzr branch         make a copy of another branch
289
 
 
290
 
  bzr add            make files or directories versioned
291
 
  bzr ignore         ignore a file or pattern
292
 
  bzr mv             move or rename a versioned file
293
 
 
294
 
  bzr status         summarize changes in working copy
295
 
  bzr diff           show detailed diffs
296
 
 
297
 
  bzr merge          pull in changes from another branch
298
 
  bzr commit         save some or all changes
299
 
  bzr send           send changes via email
300
 
 
301
 
  bzr log            show history of changes
302
 
  bzr check          validate storage
303
 
 
304
 
  bzr help init      more help on e.g. init command
305
 
  bzr help commands  list all commands
306
 
  bzr help topics    list all help topics
307
 
""" % bzrlib.__version__
 
287
  brz init           makes this directory a versioned branch
 
288
  brz branch         make a copy of another branch
 
289
 
 
290
  brz add            make files or directories versioned
 
291
  brz ignore         ignore a file or pattern
 
292
  brz mv             move or rename a versioned file
 
293
 
 
294
  brz status         summarize changes in working copy
 
295
  brz diff           show detailed diffs
 
296
 
 
297
  brz merge          pull in changes from another branch
 
298
  brz commit         save some or all changes
 
299
  brz send           send changes via email
 
300
 
 
301
  brz log            show history of changes
 
302
  brz check          validate storage
 
303
 
 
304
  brz help init      more help on e.g. init command
 
305
  brz help commands  list all commands
 
306
  brz help topics    list all help topics
 
307
""" % breezy.__version__
308
308
 
309
309
 
310
310
_global_options = \
311
311
"""Global Options
312
312
 
313
313
These options may be used with any command, and may appear in front of any
314
 
command.  (e.g. ``bzr --profile help``).
 
314
command.  (e.g. ``brz --profile help``).
315
315
 
316
316
--version      Print the version number. Must be supplied before the command.
317
317
--no-aliases   Do not process command aliases when running this command.
361
361
Checkouts are source trees that are connected to a branch, so that when
362
362
you commit in the source tree, the commit goes into that branch.  They
363
363
allow you to use a simpler, more centralized workflow, ignoring some of
364
 
Bazaar's decentralized features until you want them. Using checkouts
 
364
Breezy's decentralized features until you want them. Using checkouts
365
365
with shared repositories is very similar to working with SVN or CVS, but
366
366
doesn't have the same restrictions.  And using checkouts still allows
367
367
others working on the project to use whatever workflow they like.
368
368
 
369
 
A checkout is created with the bzr checkout command (see "help checkout").
 
369
A checkout is created with the brz checkout command (see "help checkout").
370
370
You pass it a reference to another branch, and it will create a local copy
371
371
for you that still contains a reference to the branch you created the
372
372
checkout from (the master branch). Then if you make any commits they will be
374
374
facilitates lockstep development, where each developer is working together,
375
375
continuously integrating the changes of others.
376
376
 
377
 
However the checkout is still a first class branch in Bazaar terms, so that
 
377
However the checkout is still a first class branch in Breezy terms, so that
378
378
you have the full history locally.  As you have a first class branch you can
379
379
also commit locally if you want, for instance due to the temporary loss af a
380
380
network connection. Use the --local option to commit to do this. All the local
384
384
If you are using a checkout from a shared branch you will periodically want to
385
385
pull in all the changes made by others. This is done using the "update"
386
386
command. The changes need to be applied before any non-local commit, but
387
 
Bazaar will tell you if there are any changes and suggest that you use this
 
387
Breezy will tell you if there are any changes and suggest that you use this
388
388
command when needed.
389
389
 
390
390
It is also possible to create a "lightweight" checkout by passing the
442
442
_repositories = \
443
443
"""Repositories
444
444
 
445
 
Repositories in Bazaar are where committed information is stored. There is
 
445
Repositories in Breezy are where committed information is stored. There is
446
446
a repository associated with every branch.
447
447
 
448
 
Repositories are a form of database. Bzr will usually maintain this for
 
448
Repositories are a form of database. Breezy will usually maintain this for
449
449
good performance automatically, but in some situations (e.g. when doing
450
 
very many commits in a short time period) you may want to ask bzr to
451
 
optimise the database indices. This can be done by the 'bzr pack' command.
 
450
very many commits in a short time period) you may want to ask brz to
 
451
optimise the database indices. This can be done by the 'brz pack' command.
452
452
 
453
 
By default just running 'bzr init' will create a repository within the new
 
453
By default just running 'brz init' will create a repository within the new
454
454
branch but it is possible to create a shared repository which allows multiple
455
455
branches to share their information in the same location. When a new branch is
456
456
created it will first look to see if there is a containing shared repository it
462
462
 
463
463
To create a shared repository use the init-repository command (or the alias
464
464
init-repo). This command takes the location of the repository to create. This
465
 
means that 'bzr init-repository repo' will create a directory named 'repo',
 
465
means that 'brz init-repository repo' will create a directory named 'repo',
466
466
which contains a shared repository. Any new branches that are created in this
467
467
directory will then use it for storage.
468
468
 
498
498
difficult to deal with remotely.
499
499
 
500
500
If you have a branch with no working tree you can use the 'checkout' command
501
 
to create a working tree. If you run 'bzr checkout .' from the branch it will
 
501
to create a working tree. If you run 'brz checkout .' from the branch it will
502
502
create the working tree. If the branch is updated remotely, you can update the
503
 
working tree by running 'bzr update' in that directory.
 
503
working tree by running 'brz update' in that directory.
504
504
 
505
505
If you have a branch with a working tree that you do not want the 'remove-tree'
506
506
command will remove the tree if it is safe. This can be done to avoid the
507
507
warning about the remote working tree not being updated when pushing to the
508
508
branch. It can also be useful when working with a '--no-trees' repository
509
 
(see 'bzr help repositories').
 
509
(see 'brz help repositories').
510
510
 
511
511
If you want to have a working tree on a remote machine that you push to you
512
 
can either run 'bzr update' in the remote branch after each push, or use some
 
512
can either run 'brz update' in the remote branch after each push, or use some
513
513
other method to update the tree during the push. There is an 'rspush' plugin
514
514
that will update the working tree using rsync as well as doing a push. There
515
 
is also a 'push-and-update' plugin that automates running 'bzr update' via SSH
 
515
is also a 'push-and-update' plugin that automates running 'brz update' via SSH
516
516
after each push.
517
517
 
518
518
Useful commands::
534
534
 
535
535
In addition, one branch may be bound to another one.  Binding to another
536
536
branch indicates that commits which happen in this branch must also 
537
 
happen in the other branch.  Bazaar ensures consistency by not allowing 
 
537
happen in the other branch.  Breezy ensures consistency by not allowing 
538
538
commits when the two branches are out of date.  In order for a commit 
539
539
to succeed, it may be necessary to update the current branch using 
540
 
``bzr update``.
 
540
``brz update``.
541
541
 
542
542
Related commands::
543
543
 
553
553
 
554
554
A standalone tree is a working tree with an associated repository. It
555
555
is an independently usable branch, with no dependencies on any other.
556
 
Creating a standalone tree (via bzr init) is the quickest way to put
 
556
Creating a standalone tree (via brz init) is the quickest way to put
557
557
an existing project under version control.
558
558
 
559
559
Related Commands::
578
578
  - File unversioned
579
579
  R File renamed
580
580
  ? File unknown
581
 
  X File nonexistent (and unknown to bzr)
 
581
  X File nonexistent (and unknown to brz)
582
582
  C File has conflicts
583
583
  P Entry for a pending merge (not a file)
584
584
 
596
596
 
597
597
 
598
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."),
 
599
    ("BRZPATH", "Path where brz is to look for shell plugin external commands."),
 
600
    ("BRZ_EMAIL", "E-Mail address of the user. Overrides EMAIL."),
601
601
    ("EMAIL", "E-Mail address of the user."),
602
 
    ("BZR_EDITOR", "Editor for editing commit messages. Overrides EDITOR."),
 
602
    ("BRZ_EDITOR", "Editor for editing commit messages. Overrides EDITOR."),
603
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)."),
 
604
    ("BRZ_PLUGIN_PATH", "Paths where brz should look for plugins."),
 
605
    ("BRZ_DISABLE_PLUGINS", "Plugins that brz should not load."),
 
606
    ("BRZ_PLUGINS_AT", "Plugins to load from a directory not in BRZ_PLUGIN_PATH."),
 
607
    ("BRZ_HOME", "Directory holding .bazaar config dir. Overrides HOME."),
 
608
    ("BRZ_HOME (Win32)", "Directory holding bazaar config dir. Overrides APPDATA and HOME."),
 
609
    ("BZR_REMOTE_PATH", "Full name of remote 'brz' command (for brz+ssh:// URLs)."),
 
610
    ("BRZ_SSH", "Path to SSH client, or one of paramiko, openssh, sshcorp, plink or lsh."),
 
611
    ("BRZ_LOG", "Location of .brz.log (use '/dev/null' to suppress log)."),
 
612
    ("BRZ_LOG (Win32)", "Location of .brz.log (use 'NUL' to suppress log)."),
 
613
    ("BRZ_COLUMNS", "Override implicit terminal width."),
 
614
    ("BRZ_CONCURRENCY", "Number of processes that can be run concurrently (selftest)"),
 
615
    ("BRZ_PROGRESS_BAR", "Override the progress display. Values are 'none' or 'text'."),
 
616
    ("BRZ_PDB", "Control whether to launch a debugger on error."),
 
617
    ("BRZ_SIGQUIT_PDB", "Control whether SIGQUIT behaves normally or invokes a breakin debugger."),
 
618
    ("BRZ_TEXTUI_INPUT", "Force console input mode for prompts to line-based (instead of char-based)."),
619
619
    ]
620
620
 
621
621
def _env_variables(topic):
622
622
    import textwrap
623
623
    ret = ["Environment Variables\n\n"
624
 
        "See bzr help configuration for more details.\n\n"]
 
624
        "See brz help configuration for more details.\n\n"]
625
625
    max_key_len = max([len(k[0]) for k in known_env_variables])
626
626
    desc_len = (80 - max_key_len - 2)
627
627
    ret.append("=" * max_key_len + " " + "=" * desc_len + "\n")
660
660
A criss-cross in the branch history can cause the default merge technique
661
661
to emit more conflicts than would normally be expected.
662
662
 
663
 
In complex merge cases, ``bzr merge --lca`` or ``bzr merge --weave`` may give
664
 
better results.  You may wish to ``bzr revert`` the working tree and merge
665
 
again.  Alternatively, use ``bzr remerge`` on particular conflicted files.
 
663
In complex merge cases, ``brz merge --lca`` or ``brz merge --weave`` may give
 
664
better results.  You may wish to ``brz revert`` the working tree and merge
 
665
again.  Alternatively, use ``brz remerge`` on particular conflicted files.
666
666
 
667
667
Criss-crosses occur in a branch's history if two branches merge the same thing
668
668
and then merge one another, or if two branches merge one another at the same
669
669
time.  They can be avoided by having each branch only merge from or into a
670
670
designated central branch (a "star topology").
671
671
 
672
 
Criss-crosses cause problems because of the way merge works.  Bazaar's default
 
672
Criss-crosses cause problems because of the way merge works.  Breezy's default
673
673
merge is a three-way merger; in order to merge OTHER into THIS, it must
674
674
find a basis for comparison, BASE.  Using BASE, it can determine whether
675
675
differences between THIS and OTHER are due to one side adding lines, or
677
677
 
678
678
Criss-crosses mean there is no good choice for a base.  Selecting the recent
679
679
merge points could cause one side's changes to be silently discarded.
680
 
Selecting older merge points (which Bazaar does) mean that extra conflicts
 
680
Selecting older merge points (which Breezy does) mean that extra conflicts
681
681
are emitted.
682
682
 
683
683
The ``weave`` merge type is not affected by this problem because it uses
691
691
a local branch must be destroyed.  (For checkouts, this is the local branch
692
692
that serves primarily as a cache.)  If the branch-to-be-destroyed does not
693
693
have the same last revision as the new reference branch for the lightweight
694
 
checkout, data could be lost, so Bazaar refuses.
 
694
checkout, data could be lost, so Breezy refuses.
695
695
 
696
696
How you deal with this depends on *why* the branches are out of sync.
697
697
 
698
698
If you have a checkout and have done local commits, you can get back in sync
699
 
by running "bzr update" (and possibly "bzr commit").
 
699
by running "brz update" (and possibly "brz commit").
700
700
 
701
701
If you have a branch and the remote branch is out-of-date, you can push
702
 
the local changes using "bzr push".  If the local branch is out of date, you
703
 
can do "bzr pull".  If both branches have had changes, you can merge, commit
 
702
the local changes using "brz push".  If the local branch is out of date, you
 
703
can do "brz pull".  If both branches have had changes, you can merge, commit
704
704
and then push your changes.  If you decide that some of the changes aren't
705
705
useful, you can "push --overwrite" or "pull --overwrite" instead.
706
706
"""
710
710
"""Storage Formats
711
711
 
712
712
To ensure that older clients do not access data incorrectly,
713
 
Bazaar's policy is to introduce a new storage format whenever
 
713
Breezy's policy is to introduce a new storage format whenever
714
714
new features requiring new metadata are added. New storage
715
715
formats may also be introduced to improve performance and
716
716
scalability.
744
744
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
745
745
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
746
746
def get_current_formats_topic(topic):
747
 
    from bzrlib import controldir
 
747
    from breezy import controldir
748
748
    return "Current Storage Formats\n\n" + \
749
749
        controldir.format_registry.help_topic(topic)
750
750
def get_other_formats_topic(topic):
751
 
    from bzrlib import controldir
 
751
    from breezy import controldir
752
752
    return "Other Storage Formats\n\n" + \
753
753
        controldir.format_registry.help_topic(topic)
754
754
topic_registry.register('current-formats', get_current_formats_topic,
758
758
topic_registry.register('standard-options', _standard_options,
759
759
                        'Options that can be used with any command')
760
760
topic_registry.register('global-options', _global_options,
761
 
                    'Options that control how Bazaar runs')
 
761
                    'Options that control how Breezy runs')
762
762
topic_registry.register('urlspec', _help_on_transport,
763
763
                        "Supported transport protocols")
764
764
topic_registry.register('status-flags', _status_flags,
765
765
                        "Help on status flags")
766
766
def get_bugs_topic(topic):
767
 
    from bzrlib import bugtracker
 
767
    from breezy import bugtracker
768
768
    return ("Bug Tracker Settings\n\n" +
769
769
        bugtracker.tracker_registry.help_topic(topic))
770
770
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker settings')
772
772
                        'Environment variable names and values')
773
773
topic_registry.register('files', _files,
774
774
                        'Information on configuration and log files')
775
 
topic_registry.register_lazy('hooks', 'bzrlib.hooks', 'hooks_help_text',
 
775
topic_registry.register_lazy('hooks', 'breezy.hooks', 'hooks_help_text',
776
776
                        'Points at which custom processing can be added')
777
 
topic_registry.register_lazy('location-alias', 'bzrlib.directory_service',
 
777
topic_registry.register_lazy('location-alias', 'breezy.directory_service',
778
778
                        'AliasDirectory.help_text',
779
779
                        'Aliases for remembered locations')
780
780
 
837
837
 
838
838
 
839
839
class HelpTopicIndex(object):
840
 
    """A index for bzr help that returns topics."""
 
840
    """A index for brz help that returns topics."""
841
841
 
842
842
    def __init__(self):
843
843
        self.prefix = ''
913
913
            line = line[1:]
914
914
        elif line.endswith('::'):
915
915
            line = line[:-1]
916
 
        # Map :doc:`xxx-help` to ``bzr help xxx``
917
 
        line = re.sub(":doc:`(.+?)-help`", r'``bzr help \1``', line)
 
916
        # Map :doc:`xxx-help` to ``brz help xxx``
 
917
        line = re.sub(":doc:`(.+?)-help`", r'``brz help \1``', line)
918
918
        result.append(line)
919
919
    return "\n".join(result) + "\n"
920
920