Rev 2492: (James Westby) Add a help topic for working trees and repositories. in http://bzr.arbash-meinel.com/branches/bzr/jam-integration
John Arbash Meinel
john at arbash-meinel.com
Thu May 24 16:26:59 BST 2007
At http://bzr.arbash-meinel.com/branches/bzr/jam-integration
------------------------------------------------------------
revno: 2492
revision-id: john at arbash-meinel.com-20070524152641-2vq63484l18cy4e8
parent: pqm at pqm.ubuntu.com-20070524130959-7zpl03vgx35bezhf
parent: jw+debian at jameswestby.net-20070514204516-6bnkhae4x3cx3z1k
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: jam-integration
timestamp: Thu 2007-05-24 10:26:41 -0500
message:
(James Westby) Add a help topic for working trees and repositories.
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/builtins.py builtins.py-20050830033751-fc01482b9ca23183
bzrlib/help_topics.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
bzrlib/tests/blackbox/test_help.py test_help.py-20060216004358-4ee8a2a338f75a62
------------------------------------------------------------
revno: 2485.1.3
revision-id: jw+debian at jameswestby.net-20070514204516-6bnkhae4x3cx3z1k
parent: jw+debian at jameswestby.net-20070514204247-mcxwep2on9g5p30w
committer: James Westby <jw+debian at jameswestby.net>
branch nick: bzr.repohelp
timestamp: Mon 2007-05-14 21:45:16 +0100
message:
Add a NEWS entry for the changes.
------------------------------------------------------------
revno: 2485.1.2
revision-id: jw+debian at jameswestby.net-20070514204247-mcxwep2on9g5p30w
parent: jw+debian at jameswestby.net-20070514193026-3itaozap05k3vuxp
committer: James Westby <jw+debian at jameswestby.net>
branch nick: bzr.repohelp
timestamp: Mon 2007-05-14 21:42:47 +0100
message:
Update with comments from review, thanks to John and Aaron.
------------------------------------------------------------
revno: 2485.1.1
revision-id: jw+debian at jameswestby.net-20070514193026-3itaozap05k3vuxp
parent: pqm at pqm.ubuntu.com-20070510055501-w262sk5hl33vmd19
parent: jw+debian at jameswestby.net-20070414025144-qv17v6rkq1tfu6v8
committer: James Westby <jw+debian at jameswestby.net>
branch nick: bzr.repohelp
timestamp: Mon 2007-05-14 20:30:26 +0100
message:
Update the help topics to the latest bzr.dev.
------------------------------------------------------------
revno: 2401.2.2
revision-id: jw+debian at jameswestby.net-20070414025144-qv17v6rkq1tfu6v8
parent: jw+debian at jameswestby.net-20070414010244-4qvkerl2bztwchn1
committer: James Westby <jw+debian at jameswestby.net>
branch nick: bzr.dev.repos
timestamp: Sat 2007-04-14 03:51:44 +0100
message:
Add a working-trees help topic.
Has both some general information and specifics about dealing with remote
working trees. Because of that change the remote tree warning message to point
to it. Hopefully that will give users a starting point for deciding how to
cope with that situation.
------------------------------------------------------------
revno: 2401.2.1
revision-id: jw+debian at jameswestby.net-20070414010244-4qvkerl2bztwchn1
parent: pqm at pqm.ubuntu.com-20070405073143-8fa894c829ab5e50
committer: James Westby <jw+debian at jameswestby.net>
branch nick: bzr.dev.repos
timestamp: Sat 2007-04-14 02:02:44 +0100
message:
Add a help topic for repositories.
-------------- next part --------------
=== modified file 'NEWS'
--- a/NEWS 2007-05-24 11:54:07 +0000
+++ b/NEWS 2007-05-24 15:26:41 +0000
@@ -8,6 +8,12 @@
is specified, and are labelled "revision-id:", as per mainline
revisions, instead of "merged:". (Kent Gibson)
+ IMPROVEMENTS:
+
+ * There are two new help topics, working-trees and repositories that
+ attempt to explain these concepts. (James Westby, John Arbash Meinel,
+ Aaron Bentley)
+
BUGFIXES:
* ``bzr push`` should only connect to the remote location one time.
=== modified file 'bzrlib/builtins.py'
--- a/bzrlib/builtins.py 2007-05-24 11:54:07 +0000
+++ b/bzrlib/builtins.py 2007-05-24 15:26:41 +0000
@@ -249,7 +249,7 @@
To re-create the working tree, use "bzr checkout".
"""
- _see_also = ['checkout']
+ _see_also = ['checkout', 'working-trees']
takes_args = ['location?']
@@ -669,7 +669,7 @@
location can be accessed.
"""
- _see_also = ['pull', 'update']
+ _see_also = ['pull', 'update', 'working-trees']
takes_options = ['remember', 'overwrite', 'verbose',
Option('create-prefix',
help='Create the path leading up to the branch '
@@ -812,8 +812,9 @@
try:
tree_to = dir_to.open_workingtree()
except errors.NotLocalUrl:
- warning('This transport does not update the working '
- 'tree of: %s' % (br_to.base,))
+ warning("This transport does not update the working "
+ "tree of: %s. See 'bzr help working-trees' for "
+ "more information." % br_to.base)
push_result = br_from.push(br_to, overwrite)
except errors.NoWorkingTree:
push_result = br_from.push(br_to, overwrite)
@@ -1017,7 +1018,7 @@
'bzr revert' instead of 'bzr commit' after the update.
"""
- _see_also = ['pull']
+ _see_also = ['pull', 'working-trees']
takes_args = ['dir?']
aliases = ['up']
@@ -1061,7 +1062,7 @@
Branches and working trees will also report any missing revisions.
"""
- _see_also = ['revno']
+ _see_also = ['revno', 'working-trees', 'repositories']
takes_args = ['location?']
takes_options = ['verbose']
@@ -1312,8 +1313,11 @@
class cmd_init_repository(Command):
"""Create a shared repository to hold branches.
- New branches created under the repository directory will store their revisions
- in the repository, not in the branch directory.
+ New branches created under the repository directory will store their
+ revisions in the repository, not in the branch directory.
+
+ If the --no-trees option is used then the branches in the repository
+ will not have working trees by default.
example:
bzr init-repo --no-trees repo
@@ -1321,6 +1325,8 @@
bzr checkout --lightweight repo/trunk trunk-checkout
cd trunk-checkout
(add files here)
+
+ See 'bzr help repositories' for more information.
"""
_see_also = ['init', 'branch', 'checkout']
=== modified file 'bzrlib/help_topics.py'
--- a/bzrlib/help_topics.py 2007-04-23 06:55:58 +0000
+++ b/bzrlib/help_topics.py 2007-05-14 20:42:47 +0000
@@ -276,6 +276,82 @@
commits are only made locally
"""
+_repositories = \
+"""Repositories
+
+Repositories in Bazaar are where committed information is stored. It is
+possible to create a shared repository which allows multiple branches to
+share their information in the same location. When a new branch is
+created it will first look to see if there is a containing repository it
+can share.
+
+When two branches of the same project share a repository, there is
+generally a large space saving. For some operations (e.g. branching
+within the repository) this translates in to a large time saving.
+
+To create a shared repository use the init-repository command (or the alias
+init-repo). This command takes the location of the repository to create. This
+means that 'bzr init-repository repo' will create a directory named 'repo',
+which contains a shared repository. Any new branches that are created in this
+directory will then use it for storage.
+
+It is a good idea to create a repository whenever you might create more
+than one branch of a project. This is true for both working areas where you
+are doing the development, and any server areas that you use for hosting
+projects. In the latter case, it is common to want branches without working
+trees. Since the files in the branch will not be edited directly there is no
+need to use up disk space for a working tree. To create a repository in which
+the branches will not have working trees pass the '--no-trees' option to
+'init-repository'.
+
+Related commands:
+
+ init-repository Create a shared repository. Use --no-trees to create one
+ in which new branches won't get a working tree.
+"""
+
+
+_working_trees = \
+"""Working Trees
+
+A working tree is the contents of a branch placed on disk so that you can
+see the files and edit them. The working tree is where you make changes to a
+branch, and when you commit the current state of the working tree is the
+snapshot that is recorded in the commit.
+
+When you push a branch to a remote system, a working tree will not be
+created. If one is already present the files will not be updated. The
+branch information will be updated and the working tree will be marked
+as out-of-date. Updating a working tree remotely is difficult, as there
+may be uncommitted changes or the update may cause content conflicts that are
+difficult to deal with remotely.
+
+If you have a branch with no working tree you can use the 'checkout' command
+to create a working tree. If you run 'bzr checkout .' from the branch it will
+create the working tree. If the branch is updated remotely, you can update the
+working tree by running 'bzr update' in that directory.
+
+If you have a branch with a working tree that you do not want the 'remove-tree'
+command will remove the tree if it is safe. This can be done to avoid the
+warning about the remote working tree not being updated when pushing to the
+branch. It can also be useful when working with a '--no-trees' repository
+(see 'bzr help repositories').
+
+If you want to have a working tree on a remote machine that you push to you
+can either run 'bzr update' in the remote branch after each push, or use some
+other method to update the tree during the push. There is an 'rspush' plugin
+that will update the working tree using rsync as well as doing a push. There
+is also a 'push-and-update' plugin that automates running 'bzr update' via SSH
+after each push.
+
+Useful commands:
+
+ checkout Create a working tree when a branch does not have one.
+ remove-tree Removes the working tree from a branch when it is safe to do so.
+ update When a working tree is out of sync with it's associated branch
+ this will update the tree to match the branch.
+"""
+
topic_registry.register("revisionspec", _help_on_revisionspec,
"Explain how to use --revision")
@@ -295,6 +371,10 @@
from bzrlib import bugtracker
return bugtracker.tracker_registry.help_topic(topic)
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker support')
+topic_registry.register('repositories', _repositories,
+ 'Basic information on shared repositories.')
+topic_registry.register('working-trees', _working_trees,
+ 'Information on working trees')
class HelpTopicIndex(object):
@@ -355,3 +435,4 @@
def get_help_topic(self):
"""Return the help topic this can be found under."""
return self.topic
+
=== modified file 'bzrlib/tests/blackbox/test_help.py'
--- a/bzrlib/tests/blackbox/test_help.py 2007-04-21 12:22:15 +0000
+++ b/bzrlib/tests/blackbox/test_help.py 2007-05-14 20:42:47 +0000
@@ -19,6 +19,7 @@
"""
+import bzrlib
from bzrlib.tests.blackbox import ExternalBase
@@ -69,6 +70,16 @@
self.assertContainsRe(out, 'https://')
self.assertContainsRe(out, 'sftp://')
+ def test_help_repositories(self):
+ """Smoke test for 'bzr help repositories'"""
+ out, err = self.runbzr('help repositories')
+ self.assertEqual(bzrlib.help_topics._repositories, out)
+
+ def test_help_working_trees(self):
+ """Smoke test for 'bzr help working-trees'"""
+ out, err = self.runbzr('help working-trees')
+ self.assertEqual(bzrlib.help_topics._working_trees, out)
+
def test_help_commands(self):
dash_help = self.runbzr('--help commands')[0]
commands = self.runbzr('help commands')[0]
More information about the bazaar-commits
mailing list