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
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``.
279
306
"""Global Options
281
308
These options may be used with any command, and may appear in front of any
282
command. (e.g. "bzr --profile help").
309
command. (e.g. ``bzr --profile help``).
284
311
--version Print the version number. Must be supplied before the command.
285
312
--no-aliases Do not process command aliases when running this command.
286
313
--builtin Use the built-in version of a command, not the plugin version.
287
314
This does not suppress other plugin effects.
288
315
--no-plugins Do not process any plugins.
316
--concurrency Number of processes that can be run concurrently (selftest).
290
318
--profile Profile execution using the hotshot profiler.
291
319
--lsprof Profile execution using the lsprof profiler.
297
325
will be a pickle.
298
326
--coverage Generate line coverage report in the specified directory.
300
See doc/developers/profiling.txt for more information on profiling.
328
See http://doc.bazaar.canonical.com/developers/profiling.html for more
329
information on profiling.
301
331
A number of debug flags are also available to assist troubleshooting and
304
-Dauth Trace authentication sections used.
305
-Derror Instead of normal error handling, always print a traceback
307
-Devil Capture call sites that do expensive or badly-scaling
309
-Dfetch Trace history copying between repositories.
310
-Dgraph Trace graph traversal.
311
-Dhashcache Log every time a working file is read to determine its hash.
312
-Dhooks Trace hook execution.
313
-Dhpss Trace smart protocol requests and responses.
314
-Dhttp Trace http connections, requests and responses
315
-Dindex Trace major index operations.
316
-Dknit Trace knit operations.
317
-Dlock Trace when lockdir locks are taken or released.
318
-Dmerge Emit information for debugging merges.
319
-Dpack Emit information about pack operations.
320
-Dsftp Trace SFTP internals.
332
development. See :doc:`debug-flags-help`.
323
335
_standard_options = \
324
336
"""Standard Options
326
338
Standard options are legal for all commands.
328
340
--help, -h Show help message.
329
341
--verbose, -v Display more information.
330
342
--quiet, -q Only display errors and warnings.
383
395
Another possible use for a checkout is to use it with a treeless repository
384
396
containing your branches, where you maintain only one working tree by
385
switching the master branch that the checkout points to when you want to
397
switching the master branch that the checkout points to when you want to
386
398
work on a different branch.
388
400
Obviously to commit on a checkout you need to be able to write to the master
395
407
bind"). This will change the location that the commits are sent to. The bind
396
408
command can also be used to turn a branch into a heavy checkout. If you
397
409
would like to convert your heavy checkout into a normal branch so that every
398
commit is local, you can use the "unbind" command.
410
commit is local, you can use the "unbind" command. To see whether or not a
411
branch is bound or not you can use the "info" command. If the branch is bound
412
it will tell you the location of the bound branch.
400
414
Related commands::
404
418
update Pull any changes in the master branch in to your checkout
405
419
commit Make a commit that is sent to the master branch. If you have
406
a heavy checkout then the --local option will commit to the
420
a heavy checkout then the --local option will commit to the
407
421
checkout without sending the commit to the master
408
422
bind Change the master branch that the commits in the checkout will
410
424
unbind Turn a heavy checkout into a standalone branch so that any
411
425
commits are only made locally
426
info Displays whether a branch is bound or unbound. If the branch is
427
bound, then it will also display the location of the bound branch
414
430
_repositories = \
420
436
Repositories are a form of database. Bzr will usually maintain this for
421
437
good performance automatically, but in some situations (e.g. when doing
422
very many commits in a short time period) you may want to ask bzr to
438
very many commits in a short time period) you may want to ask bzr to
423
439
optimise the database indices. This can be done by the 'bzr pack' command.
425
441
By default just running 'bzr init' will create a repository within the new
572
588
BZR_HOME Directory holding .bazaar config dir. Overrides HOME.
573
589
BZR_HOME (Win32) Directory holding bazaar config dir. Overrides APPDATA and HOME.
574
590
BZR_REMOTE_PATH Full name of remote 'bzr' command (for bzr+ssh:// URLs).
575
BZR_SSH SSH client: paramiko (default), openssh, ssh, plink.
591
BZR_SSH Path to SSH client, or one of paramiko, openssh, sshcorp, plink.
576
592
BZR_LOG Location of .bzr.log (use '/dev/null' to suppress log).
577
593
BZR_LOG (Win32) Location of .bzr.log (use 'NUL' to suppress log).
594
BZR_COLUMNS Override implicit terminal width.
595
BZR_CONCURRENCY Number of processes that can be run concurrently (selftest).
578
596
================ =================================================================
661
679
formats may also be introduced to improve performance and
664
Use the following guidelines to select a format (stopping
665
as soon as a condition is true):
667
* If you are working on an existing project, use whatever
668
format that project is using. (Bazaar will do this for you
671
* If you are using bzr-svn to interoperate with a Subversion
672
repository, use 1.9-rich-root.
674
* If you are working on a project with big trees (5000+ paths)
675
or deep history (5000+ revisions), use 1.9.
677
* Otherwise, use the default format - it is good enough for
680
If some of your developers are unable to use the most recent
681
version of Bazaar (due to distro package availability say), be
682
sure to adjust the guidelines above accordingly. For example,
683
you may need to select 1.6 instead of 1.9 if your project has
684
standardized on Bazaar 1.7.
686
Note: Many of the currently supported formats have two variants:
687
a plain one and a rich-root one. The latter include an additional
688
field about the root of the tree. There is no performance cost
689
for using a rich-root format but you cannot easily merge changes
690
from a rich-root format into a plain format. As a consequence,
691
moving a project to a rich-root format takes some co-ordination
692
in that all contributors need to upgrade their repositories
693
around the same time. (It is for this reason that we have delayed
694
making a rich-root format the default so far, though we will do
695
so at some appropriate time in the future.)
697
See ``bzr help current-formats`` for the complete list of
698
currently supported formats. See ``bzr help other-formats`` for
682
The newest format, 2a, is highly recommended. If your
683
project is not using 2a, then you should suggest to the
684
project owner to upgrade.
689
Some of the older formats have two variants:
690
a plain one and a rich-root one. The latter include an additional
691
field about the root of the tree. There is no performance cost
692
for using a rich-root format but you cannot easily merge changes
693
from a rich-root format into a plain format. As a consequence,
694
moving a project to a rich-root format takes some co-ordination
695
in that all contributors need to upgrade their repositories
696
around the same time. 2a and all future formats will be
697
implicitly rich-root.
699
See :doc:`current-formats-help` for the complete list of
700
currently supported formats. See :doc:`other-formats-help` for
699
701
descriptions of any available experimental and deprecated formats.
727
729
"Help on status flags")
728
730
def get_bugs_topic(topic):
729
731
from bzrlib import bugtracker
730
return ("Bug Tracker Settings\n\n" +
732
return ("Bug Tracker Settings\n\n" +
731
733
bugtracker.tracker_registry.help_topic(topic))
732
734
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker settings')
733
735
topic_registry.register('env-variables', _env_variables,
734
736
'Environment variable names and values')
735
737
topic_registry.register('files', _files,
736
738
'Information on configuration and log files')
739
topic_registry.register_lazy('hooks', 'bzrlib.hooks', 'hooks_help_text',
740
'Points at which custom processing can be added')
738
# Load some of the help topics from files
742
# Load some of the help topics from files. Note that topics which reproduce API
743
# details will tend to skew (quickly usually!) so please seek other solutions
739
745
topic_registry.register('authentication', _load_from_file,
740
746
'Information on configuring authentication')
741
747
topic_registry.register('configuration', _load_from_file,
742
748
'Details on the configuration settings available')
743
topic_registry.register('conflicts', _load_from_file,
749
topic_registry.register('conflict-types', _load_from_file,
744
750
'Types of conflicts and what to do about them')
745
topic_registry.register('hooks', _load_from_file,
746
'Points at which custom processing can be added')
751
topic_registry.register('debug-flags', _load_from_file,
752
'Options to show or record debug information')
753
topic_registry.register('log-formats', _load_from_file,
754
'Details on the logging formats available')
749
757
# Register concept topics.
754
762
'Information on what a branch is', SECT_CONCEPT)
755
763
topic_registry.register('checkouts', _checkouts,
756
764
'Information on what a checkout is', SECT_CONCEPT)
765
topic_registry.register('content-filters', _load_from_file,
766
'Conversion of content into/from working trees',
768
topic_registry.register('diverged-branches', _load_from_file,
769
'How to fix diverged branches',
771
topic_registry.register('eol', _load_from_file,
772
'Information on end-of-line handling',
757
774
topic_registry.register('formats', _storage_formats,
758
775
'Information on choosing a storage format',
822
839
returned instead of plain text.
824
841
result = topic_registry.get_detail(self.topic)
825
# there is code duplicated here and in bzrlib/plugin.py's
842
# there is code duplicated here and in bzrlib/plugin.py's
826
843
# matching Topic code. This should probably be factored in
827
844
# to a helper function and a common base class.
828
845
if additional_see_also is not None:
added
removed
bzrlib/help_topics/__init__.py
