Rev 4415: Merge bzr.dev 4443, resolve NEWS in http://bazaar.launchpad.net/~jameinel/bzr/1.16-better_heads

[John Arbash Meinel]

At http://bazaar.launchpad.net/~jameinel/bzr/1.16-better_heads

------------------------------------------------------------
revno: 4415 [merge]
revision-id: john at arbash-meinel.com-20090615171536-ef0rtljwjmrei7on
parent: john at arbash-meinel.com-20090615170430-bd6ulrllik7xkwpv
parent: pqm at pqm.ubuntu.com-20090615170647-5zu6h93br8c4ue6i
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: 1.16-better_heads
timestamp: Mon 2009-06-15 12:15:36 -0500
message:
  Merge bzr.dev 4443, resolve NEWS
added:
  bzrlib/help_topics/en/diverged-branches.txt divergedbranches.txt-20090608035534-mb4ry8so4hw238n0-1
modified:
  NEWS                           NEWS-20050323055033-4e00b5db738777ff
  bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
  bzrlib/push.py                 push.py-20080606021927-5fe39050e8xne9un-1
  bzrlib/tests/blackbox/test_push.py test_push.py-20060329002750-929af230d5d22663
-------------- next part --------------
=== modified file 'NEWS'
--- a/NEWS	2009-06-15 17:04:30 +0000
+++ b/NEWS	2009-06-15 17:15:36 +0000
@@ -9,6 +9,14 @@
 In Development
 ##############
 
+Bug Fixes
+*********
+
+* Add documentation about diverged branches and how to fix them in the
+  centralized workflow with local commits.  Mention ``bzr help
+  diverged-branches`` when a push fails because the branches have
+  diverged.  (Neil Martinsen-Burrell, #269477)
+
 Internals
 *********
 

=== modified file 'bzrlib/help_topics/__init__.py'
--- a/bzrlib/help_topics/__init__.py	2009-06-11 06:54:33 +0000
+++ b/bzrlib/help_topics/__init__.py	2009-06-15 15:20:24 +0000
@@ -732,6 +732,8 @@
                         'Options to show or record debug information')
 topic_registry.register('log-formats', _load_from_file,
                         'Details on the logging formats available')
+topic_registry.register('diverged-branches', _load_from_file,
+                        'How to fix diverged branches')
 
 
 # Register concept topics.

=== added file 'bzrlib/help_topics/en/diverged-branches.txt'
--- a/bzrlib/help_topics/en/diverged-branches.txt	1970-01-01 00:00:00 +0000
+++ b/bzrlib/help_topics/en/diverged-branches.txt	2009-06-08 05:00:01 +0000
@@ -0,0 +1,39 @@
+Diverged Branches
+=================
+
+When Bazaar tries to push one branch onto another, it requires that the
+destination branch must be ready to receive the source branch.  If this isn't
+the case, then we say that the branches have ``diverged``.  Branches are
+considered diverged if the destination branch's most recent commit is one that
+has not been merged (directly or indirectly) by the source branch.  To recover
+from diverged branches, one must merge the missing revisions into the source
+branch.
+
+This situation commonly arises when using a centralized workflow with local
+commits.  If someone else has committed new work to the mainline since your
+last pull and you have local commits that have not yet been pushed to the
+mainline, then your local branch and the mainline have diverged.
+
+Discovering What Has Diverged
+-----------------------------
+
+The ``bzr missing`` command is used to find out what revisions are in another
+branch that are not present in the current branch, and vice-versa.  It shows a
+summary of  which extra revisions exist in each branch.  If you want to see the
+precise effects of those revisions, you can use ``bzr diff --old=other_branch``
+to show the differences between other_branch and your current branch.
+
+A Solution
+----------
+
+The solution is to merge the revisions from the mainline into your local
+branch.  To do so, use ``bzr merge`` to get the new revisions from the
+mainline.  This merge may result in conflicts if the other developer's changes
+overlap with your changes.  These conflicts should be resolved before
+continuing. After any conflicts have been resolved, or even if there were no
+conflicts, Bazaar requires that you explicitly commit these new revisions
+to your local branch.  This requirement gives you an opportunity to test the
+resulting working tree for correctness, since the merged revisions could have
+made arbitrary changes.  After testing, you should commit the merge using
+``bzr commit``.  This clears up the diverged branches situation.  Your local
+branch can now be pushed to the mainline.

=== modified file 'bzrlib/push.py'
--- a/bzrlib/push.py	2009-04-23 23:35:44 +0000
+++ b/bzrlib/push.py	2009-06-08 05:00:01 +0000
@@ -128,7 +128,8 @@
                 remember)
         except errors.DivergedBranches:
             raise errors.BzrCommandError('These branches have diverged.'
-                                    '  Try using "merge" and then "push".')
+                                    '  See "bzr help diverged-branches"'
+                                    ' for more information.')
         except errors.NoRepositoryPresent:
             # we have a bzrdir but no branch or repository
             # XXX: Figure out what to do other than complain.

=== modified file 'bzrlib/tests/blackbox/test_push.py'
--- a/bzrlib/tests/blackbox/test_push.py	2009-06-11 10:14:27 +0000
+++ b/bzrlib/tests/blackbox/test_push.py	2009-06-15 15:20:24 +0000
@@ -86,7 +86,7 @@
                            working_dir='branch_a', retcode=3)
         self.assertEquals(out,
                 ('','bzr: ERROR: These branches have diverged.  '
-                    'Try using "merge" and then "push".\n'))
+                 'See "bzr help diverged-branches" for more information.\n'))
         self.assertEquals(osutils.abspath(branch_a.get_push_location()),
                           osutils.abspath(branch_b.bzrdir.root_transport.base))