Merge lp:~abentley/bzr/branch-store into lp:bzr

[Aaron Bentley]

(abentley) Switch stores uncommitted changes in branch (Aaron Bentley)

This branch adds one of my favourite pipeline features to core Bazaar: storing and restoring uncommitted changes when switching between branches.

With colocated workflows now supported by core Bazaar, we should make them work smoothly. Storing uncommitted changes makes it convenient to switch between branches as needed.

The effect is similar to using "shelve --all" and "unshelve", but since the changes are associated with the branch instead of the working tree, bzr is able to select the correct changes automatically during the switch operation.

I have made this new mode the default because I believe it is the common case, and the least-likely to cause problems for users. Specifically, merging changes into existing branches often leads to conflicts. So for users who do not intend to apply the changes from their current branch to the new branch, there are two problems: 1. the changes are applied to the new branch, 2. The changes acquire conflicts, which makes it difficult to restore them to the original branch. By contrast, the only case where the new behaviour leads to conflicts is when the new branch has stored uncommitted changes, and the new branch's last_revision has changed since. This is possible, but not common.

There are two classes of users who may be surprised when switch merges their uncommitted changes into the new branch: users unfamiliar with switch, and users who did not realize they had uncommitted changes in their tree.

[Jelmer Vernooij (jelmer)]

On Wed, Jul 18, 2012 at 08:47:19PM -0000, Aaron Bentley wrote:
> This branch adds one of my favourite pipeline features to core
> Bazaar: storing and restoring uncommitted changes when switching
> between branches.

> With colocated workflows now supported by core Bazaar, we should
> make them work smoothly. Storing uncommitted changes makes it
> convenient to switch between branches as needed.

> The effect is similar to using "shelve --all" and "unshelve", but
> since the changes are associated with the branch instead of the
> working tree, bzr is able to select the correct changes
> automatically during the switch operation.

> I have made this new mode the default because I believe it is the
> common case, and the least-likely to cause problems for users.
> Specifically, merging changes into existing branches often leads to
> conflicts. So for users who do not intend to apply the changes from
> their current branch to the new branch, there are two problems: 1.
> the changes are applied to the new branch, 2. The changes acquire
> conflicts, which makes it difficult to restore them to the original
> branch. By contrast, the only case where the new behaviour leads to
> conflicts is when the new branch has stored uncommitted changes, and
> the new branch's last_revision has changed since. This is possible,
> but not common.

> There are two classes of users who may be surprised when switch
> merges their uncommitted changes into the new branch: users
> unfamiliar with switch, and users who did not realize they had
> uncommitted changes in their tree.
Personally, I prefer the current behaviour; it means it's possible to
switch over to a new branch easily if you happen to change a few
things that really deserve their own branch ("bzr switch -b foo && bzr
ci"). The current behaviour is also consistent with git, for what
that is worth.

If switch is going to rely on them, then the new methods on Branch
should really be public. Foreign branch support will break with this
merge proposal as-is.

Cheers,

Jelmer

[Aaron Bentley (abentley)]

> On Wed, Jul 18, 2012 at 08:47:19PM -0000, Aaron Bentley wrote:
> Personally, I prefer the current behaviour; it means it's possible to
> switch over to a new branch easily if you happen to change a few
> things that really deserve their own branch ("bzr switch -b foo && bzr
> ci").

I'm willing to leave the current behaviour as the default. I think this behaviour is safer and more convenient in most cases. Please try it out for a few weeks, and I think you'll find you want it as the default, too.

> The current behaviour is also consistent with git, for what
> that is worth.

Okay. I was under the impression git didn't automatically merge, but said "error: You have local changes to "X"; cannot switch branches." like this: http://stackoverflow.com/questions/1304626/git-switch-branch-and-ignore-any-changes-without-committing

In fact, one of my co-workers who uses git was surprised that bzr didn't behave like the above, and that was one of the reasons I worked on this.

> If switch is going to rely on them, then the new methods on Branch
> should really be public. Foreign branch support will break with this
> merge proposal as-is.

Per our IRC discussion, I'll turn get_unshelver/store_uncommitted/has_stored_uncommitted into BzrBranch methods, since implementing _put_uncommitted and _get_uncommitted on foreign branches would not be desirable (if it could be implemented at all, it would store bzr-specific data in foreign branches).

[Aaron Bentley (abentley)]

Further research suggests git only errors if the uncommitted changes *conflict*: http://www.gitguys.com/topics/switching-branches-without-committing/

[Aaron Bentley (abentley)]

Updated per our discussion. I've removed _get/_put_uncommitted and has_stored_uncommitted. The remaining functions are implemented on BzrBranch/RemoteBranch, and an exception is available for foreign branches that don't support it (I've tested it locally with bzr-svn). The behaviour is disabled by default, enabled with --store.

[Jelmer Vernooij (jelmer)]

Thanks; this looks good to land to me now. It would be good if somebody else (mgz?) could also have a quick look at it.

Would --store perhaps be better named as --shelve, since that's a term people are already familiar with?

review: Approve

[Aaron Bentley (abentley)]

> Would --store perhaps be better named as --shelve, since that's a term people
> are already familiar with?

I thought it would be confusing to use "shelf", because of the UI differences between these and shelves:

- they cannot be manipulated with "bzr shelve/unshelve"
- they don't have the same interactive UI as "bzr shelve"
- there is one store per branch, but many shelves per working tree

What do you think?

Aaron

[Jelmer Vernooij (jelmer)]

> > Would --store perhaps be better named as --shelve, since that's a term
> people
> > are already familiar with?
>
> I thought it would be confusing to use "shelf", because of the UI differences
> between these and shelves:
>
> - they cannot be manipulated with "bzr shelve/unshelve"
> - they don't have the same interactive UI as "bzr shelve"
> - there is one store per branch, but many shelves per working tree
>
> What do you think?
Hmm, I hadn't considered it that way - I guess it could indeed be confusing if looks like a shelve but isn't quite a shelve. Let me retract that suggestion.

[Martin Packman (gz)]

Code all looks good, tests are helpful in explaining the intended behaviour.

Documentation is rather on the light side, a help string for a command switch and an entry in what's new isn't going to be enough for people who want this to find it.

Using --store to mean both stash the changes to the current branch and unstash the changes to the target branch is a slight stretch of english.

I'd like to see a blackbox test where both branches have stored changes.

Overall, this seems more like an alternative behaviour for switch that some people might want to configure on all the time, rather than a command line switch for situational use.

How would it work if say, you accidentally switched back to a branch with stored changes without passing --store, then commited something, then wanted to get your pending work again? Shelves are hard to recover manually, we don't want to introduce a new workflow that's likely to confuse people.

Configuring stuff off by default can be a bad compromise, we already have a bunch of good changes stuck behind an obscure option or command due to disagreements or not being finished.

Apart from question of whether this should really be a switch param rather than a config option, don't think anything should block this landing for now though.

review: Approve

[lp:~abentley/bzr/branch-store]

6570. By Aaron Bentley on 2012-07-23

Add docs on switch --store.

6571. By Aaron Bentley on 2012-07-23

Tweak docs.

6572. By Aaron Bentley on 2012-07-23

Update blackbox test to show storing and restoring in one switch.

[Aaron Bentley (abentley)]

> Documentation is rather on the light side, a help string for a command switch
> and an entry in what's new isn't going to be enough for people who want this
> to find it.

I've added switch_store.txt

> Using --store to mean both stash the changes to the current branch and unstash
> the changes to the target branch is a slight stretch of english.

Yes, but I can't think of anything better. It's also a bit of a cheat in that "store" and "restore" aren't really antonyms.

> I'd like to see a blackbox test where both branches have stored changes.

Per our IRC discussion, I've changed test_store_and_restore to include the case where the target branch has stored changes and the working tree has uncommitted changes.

> Overall, this seems more like an alternative behaviour for switch that some
> people might want to configure on all the time, rather than a command line
> switch for situational use.

Everyone will want the current default behaviour sometimes. If they alias "switch=switch --store", they can get it back with "switch --no-store". With a config option, it would be much more painful.

> How would it work if say, you accidentally switched back to a branch with
> stored changes without passing --store, then commited something, then wanted
> to get your pending work again?

You would use "bzr switch . --store" to get it back. I've added it to the docs.

> Configuring stuff off by default can be a bad compromise, we already have a
> bunch of good changes stuck behind an obscure option or command due to
> disagreements or not being finished.

Hopefully, we can revisit the default in the future. For now, this gets me an approval from jelmer.

Aaron

=== modified file 'bzrlib/branch.py'
--- bzrlib/branch.py	2012-07-06 11:27:16 +0000
+++ bzrlib/branch.py	2012-07-23 17:13:23 +0000
@@ -39,6 +39,7 @@
     repository,
     revision as _mod_revision,
     rio,
+    shelf,
     tag as _mod_tag,
     transport,
     ui,
@@ -251,6 +252,23 @@
         """
         raise NotImplementedError(self._get_config)
 
+    def store_uncommitted(self, creator):
+        """Store uncommitted changes from a ShelfCreator.
+
+        :param creator: The ShelfCreator containing uncommitted changes, or
+            None to delete any stored changes.
+        :raises: ChangesAlreadyStored if the branch already has changes.
+        """
+        raise NotImplementedError(self.store_uncommitted)
+
+    def get_unshelver(self, tree):
+        """Return a shelf.Unshelver for this branch and tree.
+
+        :param tree: The tree to use to construct the Unshelver.
+        :return: an Unshelver or None if no changes are stored.
+        """
+        raise NotImplementedError(self.get_unshelver)
+
     def _get_fallback_repository(self, url, possible_transports):
         """Get the repository we fallback to at url."""
         url = urlutils.join(self.base, url)
@@ -2386,6 +2404,45 @@
             self.conf_store =  _mod_config.BranchStore(self)
         return self.conf_store
 
+    def _uncommitted_branch(self):
+        """Return the branch that may contain uncommitted changes."""
+        master = self.get_master_branch()
+        if master is not None:
+            return master
+        else:
+            return self
+
+    def store_uncommitted(self, creator):
+        """Store uncommitted changes from a ShelfCreator.
+
+        :param creator: The ShelfCreator containing uncommitted changes, or
+            None to delete any stored changes.
+        :raises: ChangesAlreadyStored if the branch already has changes.
+        """
+        branch = self._uncommitted_branch()
+        if creator is None:
+            branch._transport.delete('stored-transform')
+            return
+        if branch._transport.has('stored-transform'):
+            raise errors.ChangesAlreadyStored
+        transform = StringIO()
+        creator.write_shelf(transform)
+        transform.seek(0)
+        branch._transport.put_file('stored-transform', transform)
+
+    def get_unshelver(self, tree):
+        """Return a shelf.Unshelver for this branch and tree.
+
+        :param tree: The tree to use to construct the Unshelver.
+        :return: an Unshelver or None if no changes are stored.
+        """
+        branch = self._uncommitted_branch()
+        try:
+            transform = branch._transport.get('stored-transform')
+        except errors.NoSuchFile:
+            return None
+        return shelf.Unshelver.from_tree_and_shelf(tree, transform)
+
     def is_locked(self):
         return self.control_files.is_locked()
 

=== modified file 'bzrlib/builtins.py'
--- bzrlib/builtins.py	2012-07-20 13:23:32 +0000
+++ bzrlib/builtins.py	2012-07-23 17:13:23 +0000
@@ -6233,10 +6233,13 @@
                      Option('create-branch', short_name='b',
                         help='Create the target branch from this one before'
                              ' switching to it.'),
+                     Option('store',
+                        help='Store and restore uncommitted changes in the'
+                             ' branch.'),
                     ]
 
     def run(self, to_location=None, force=False, create_branch=False,
-            revision=None, directory=u'.'):
+            revision=None, directory=u'.', store=False):
         from bzrlib import switch
         tree_location = directory
         revision = _get_one_revision('switch', revision)
@@ -6273,7 +6276,8 @@
                     possible_transports=possible_transports)
         if revision is not None:
             revision = revision.as_revision_id(to_branch)
-        switch.switch(control_dir, to_branch, force, revision_id=revision)
+        switch.switch(control_dir, to_branch, force, revision_id=revision,
+                      store_uncommitted=store)
         if had_explicit_nick:
             branch = control_dir.open_branch() #get the new branch!
             branch.nick = to_branch.nick

=== modified file 'bzrlib/errors.py'
--- bzrlib/errors.py	2012-06-18 11:43:07 +0000
+++ bzrlib/errors.py	2012-07-23 17:13:23 +0000
@@ -2893,6 +2893,21 @@
         BzrError.__init__(self, tree=tree, display_url=display_url, more=more)
 
 
+class StoringUncommittedNotSupported(BzrError):
+
+    _fmt = ('Branch "%(display_url)s" does not support storing uncommitted'
+            ' changes.')
+
+    def __init__(self, branch):
+        import bzrlib.urlutils as urlutils
+        user_url = getattr(branch, "user_url", None)
+        if user_url is None:
+            display_url = str(branch)
+        else:
+            display_url = urlutils.unescape_for_display(user_url, 'ascii')
+        BzrError.__init__(self, branch=branch, display_url=display_url)
+
+
 class ShelvedChanges(UncommittedChanges):
 
     _fmt = ('Working tree "%(display_url)s" has shelved changes'
@@ -3340,3 +3355,9 @@
 
     def __init__(self, feature):
         self.feature = feature
+
+
+class ChangesAlreadyStored(BzrCommandError):
+
+    _fmt = ('Cannot store uncommitted changes because this branch already'
+            ' stores uncommitted changes.')

=== modified file 'bzrlib/lock.py'
--- bzrlib/lock.py	2011-12-19 13:23:58 +0000
+++ bzrlib/lock.py	2012-07-23 17:13:23 +0000
@@ -35,6 +35,7 @@
 
 from __future__ import absolute_import
 
+import contextlib
 import errno
 import os
 import sys
@@ -548,3 +549,10 @@
             trace.note(gettext('{0!r} was {1} locked again'), self, type_name)
         self._prev_lock = lock_type
 
[e-mail]
+def write_locked(lockable):
+    lockable.lock_write()
+    try:
+        yield lockable
+    finally:
+        lockable.unlock()

=== modified file 'bzrlib/remote.py'
--- bzrlib/remote.py	2012-06-28 16:17:34 +0000
+++ bzrlib/remote.py	2012-07-23 17:13:23 +0000
@@ -3393,6 +3393,14 @@
             self.conf_store =  RemoteBranchStore(self)
         return self.conf_store
 
+    def store_uncommitted(self, creator):
+        self._ensure_real()
+        return self._real_branch.store_uncommitted(creator)
+
+    def get_unshelver(self, tree):
+        self._ensure_real()
+        return self._real_branch.get_unshelver(tree)
+
     def _get_real_transport(self):
         # if we try vfs access, return the real branch's vfs transport
         self._ensure_real()

=== modified file 'bzrlib/shelf.py'
--- bzrlib/shelf.py	2011-12-18 15:28:38 +0000
+++ bzrlib/shelf.py	2012-07-23 17:13:23 +0000
@@ -125,9 +125,14 @@
             raise ValueError('Unknown change kind: "%s"' % change[0])
 
     def shelve_all(self):
-        """Shelve all changes."""
+        """Shelve all changes.
+
+        :return: True if changes were shelved, False if there were no changes.
+        """
+        change = None
         for change in self.iter_shelvable():
             self.shelve_change(change)
+        return change is not None
 
     def shelve_rename(self, file_id):
         """Shelve a file rename.
@@ -255,6 +260,14 @@
         """Shelve changes from working tree."""
         self.work_transform.apply()
 
+    @staticmethod
+    def metadata_record(serializer, revision_id, message=None):
+        metadata = {'revision_id': revision_id}
+        if message is not None:
+            metadata['message'] = message.encode('utf-8')
+        return serializer.bytes_record(
+            bencode.bencode(metadata), (('metadata',),))
+
     def write_shelf(self, shelf_file, message=None):
         """Serialize the shelved changes to a file.
 
@@ -263,16 +276,17 @@
         :return: the filename of the written file.
         """
         transform.resolve_conflicts(self.shelf_transform)
+        revision_id = self.target_tree.get_revision_id()
+        return self._write_shelf(shelf_file, self.shelf_transform, revision_id,
+                                 message)
+
+    @classmethod
+    def _write_shelf(cls, shelf_file, transform, revision_id, message=None):
         serializer = pack.ContainerSerialiser()
         shelf_file.write(serializer.begin())
-        metadata = {
-            'revision_id': self.target_tree.get_revision_id(),
-        }
-        if message is not None:
-            metadata['message'] = message.encode('utf-8')
-        shelf_file.write(serializer.bytes_record(
-            bencode.bencode(metadata), (('metadata',),)))
-        for bytes in self.shelf_transform.serialize(serializer):
+        metadata = cls.metadata_record(serializer, revision_id, message)
+        shelf_file.write(metadata)
+        for bytes in transform.serialize(serializer):
             shelf_file.write(bytes)
         shelf_file.write(serializer.end())
 

=== modified file 'bzrlib/switch.py'
--- bzrlib/switch.py	2012-02-14 17:22:37 +0000
+++ bzrlib/switch.py	2012-07-23 17:13:23 +0000
@@ -18,7 +18,12 @@
 
 # Original author: David Allouche
 
-from bzrlib import errors, merge, revision
+from bzrlib import (
+    errors,
+    lock,
+    merge,
+    revision
+    )
 from bzrlib.branch import Branch
 from bzrlib.i18n import gettext
 from bzrlib.trace import note
@@ -32,26 +37,32 @@
     for hook in hooks:
         hook(params)
 
-def switch(control_dir, to_branch, force=False, quiet=False, revision_id=None):
+def switch(control_dir, to_branch, force=False, quiet=False, revision_id=None,
+           store_uncommitted=False):
     """Switch the branch associated with a checkout.
 
     :param control_dir: ControlDir of the checkout to change
     :param to_branch: branch that the checkout is to reference
     :param force: skip the check for local commits in a heavy checkout
     :param revision_id: revision ID to switch to.
+    :param store_uncommitted: If True, store uncommitted changes in the
+        branch.
     """
     _check_pending_merges(control_dir, force)
     try:
         source_repository = control_dir.open_branch().repository
     except errors.NotBranchError:
         source_repository = to_branch.repository
+    if store_uncommitted:
+        with lock.write_locked(control_dir.open_workingtree()) as tree:
+            tree.store_uncommitted()
     to_branch.lock_read()
     try:
         _set_branch_location(control_dir, to_branch, force)
     finally:
         to_branch.unlock()
     tree = control_dir.open_workingtree()
-    _update(tree, source_repository, quiet, revision_id)
+    _update(tree, source_repository, quiet, revision_id, store_uncommitted)
     _run_post_switch_hooks(control_dir, to_branch, force, revision_id)
 
 def _check_pending_merges(control, force=False):
@@ -151,13 +162,18 @@
     return False
 
 
-def _update(tree, source_repository, quiet=False, revision_id=None):
+def _update(tree, source_repository, quiet=False, revision_id=None,
+            restore_uncommitted=False):
     """Update a working tree to the latest revision of its branch.
 
     :param tree: the working tree
     :param source_repository: repository holding the revisions
+    :param restore_uncommitted: restore any uncommitted changes in the branch.
     """
-    tree.lock_tree_write()
+    if restore_uncommitted:
+        tree.lock_write()
+    else:
+        tree.lock_tree_write()
     try:
         to_branch = tree.branch
         if revision_id is None:
@@ -165,11 +181,14 @@
         if tree.last_revision() == revision_id:
             if not quiet:
                 note(gettext("Tree is up to date at revision %d."), to_branch.revno())
-            return
-        base_tree = source_repository.revision_tree(tree.last_revision())
-        merge.Merge3Merger(tree, tree, base_tree, to_branch.repository.revision_tree(revision_id))
-        tree.set_last_revision(to_branch.last_revision())
-        if not quiet:
-            note(gettext('Updated to revision %d.') % to_branch.revno())
+        else:
+            base_tree = source_repository.revision_tree(tree.last_revision())
+            merge.Merge3Merger(tree, tree, base_tree,
+                               to_branch.repository.revision_tree(revision_id))
+            tree.set_last_revision(to_branch.last_revision())
+            if not quiet:
+                note(gettext('Updated to revision %d.') % to_branch.revno())
+        if restore_uncommitted:
+            tree.restore_uncommitted()
     finally:
         tree.unlock()

=== modified file 'bzrlib/tests/blackbox/test_switch.py'
--- bzrlib/tests/blackbox/test_switch.py	2012-06-18 11:43:07 +0000
+++ bzrlib/tests/blackbox/test_switch.py	2012-07-23 17:13:23 +0000
@@ -304,7 +304,8 @@
 
     def test_switch_lightweight_after_branch_moved_relative(self):
         self.prepare_lightweight_switch()
-        self.run_bzr('switch --force branch1', working_dir='tree')
+        self.run_bzr('switch --force branch1',
+                     working_dir='tree')
         branch_location = WorkingTree.open('tree').branch.base
         self.assertEndsWith(branch_location, 'branch1/')
 
@@ -492,3 +493,39 @@
         self.assertLength(24, self.hpss_calls)
         self.assertLength(4, self.hpss_connections)
         self.assertThat(self.hpss_calls, ContainsNoVfsCalls)
+
+
+class TestSwitchUncommitted(TestCaseWithTransport):
+
+    def prepare(self):
+        tree = self.make_branch_and_tree('orig')
+        tree.commit('')
+        tree.branch.bzrdir.sprout('new')
+        checkout = tree.branch.create_checkout('checkout', lightweight=True)
+        self.build_tree(['checkout/a'])
+        self.assertPathExists('checkout/a')
+        checkout.add('a')
+        return checkout
+
+    def test_store_and_restore_uncommitted(self):
+        checkout = self.prepare()
+        self.run_bzr(['switch', '--store', '-d', 'checkout', 'new'])
+        self.build_tree(['checkout/b'])
+        checkout.add('b')
+        self.assertPathDoesNotExist('checkout/a')
+        self.assertPathExists('checkout/b')
+        self.run_bzr(['switch', '--store', '-d', 'checkout', 'orig'])
+        self.assertPathExists('checkout/a')
+        self.assertPathDoesNotExist('checkout/b')
+
+    def test_does_not_store(self):
+        self.prepare()
+        self.run_bzr(['switch', '-d', 'checkout', 'new'])
+        self.assertPathExists('checkout/a')
+
+    def test_does_not_restore_changes(self):
+        self.prepare()
+        self.run_bzr(['switch', '--store', '-d', 'checkout', 'new'])
+        self.assertPathDoesNotExist('checkout/a')
+        self.run_bzr(['switch', '-d', 'checkout', 'orig'])
+        self.assertPathDoesNotExist('checkout/a')

=== modified file 'bzrlib/tests/per_branch/test_branch.py'
--- bzrlib/tests/per_branch/test_branch.py	2012-03-14 11:49:29 +0000
+++ bzrlib/tests/per_branch/test_branch.py	2012-07-23 17:13:23 +0000
@@ -16,6 +16,8 @@
 
 """Tests for branch implementations - tests a branch format."""
 
+import contextlib
+
 from bzrlib import (
     branch as _mod_branch,
     controldir,
@@ -25,10 +27,12 @@
     merge,
     osutils,
     urlutils,
+    transform,
     transport,
     remote,
     repository,
     revision,
+    shelf,
     symbol_versioning,
     tests,
     )
@@ -1057,3 +1061,88 @@
         # above the control dir but we might need to relax that?
         self.assertEqual(br.control_url.find(br.user_url), 0)
         self.assertEqual(br.control_url, br.control_transport.base)
+
+
+class FakeShelfCreator(object):
+
+    def __init__(self, branch):
+        self.branch = branch
+
+    def write_shelf(self, shelf_file, message=None):
+        tree = self.branch.repository.revision_tree(revision.NULL_REVISION)
+        with transform.TransformPreview(tree) as tt:
+            shelf.ShelfCreator._write_shelf(
+                shelf_file, tt, revision.NULL_REVISION)
+
+
[e-mail]
+def skip_if_storing_uncommitted_unsupported():
+    try:
+        yield
+    except errors.StoringUncommittedNotSupported:
+        raise tests.TestNotApplicable('Cannot store uncommitted changes.')
+
+
+class TestUncommittedChanges(per_branch.TestCaseWithBranch):
+
+    def bind(self, branch, master):
+        try:
+            branch.bind(master)
+        except errors.UpgradeRequired:
+            raise tests.TestNotApplicable('Branch cannot be bound.')
+
+    def test_store_uncommitted(self):
+        tree = self.make_branch_and_tree('b')
+        branch = tree.branch
+        creator = FakeShelfCreator(branch)
+        with skip_if_storing_uncommitted_unsupported():
+            self.assertIs(None, branch.get_unshelver(tree))
+        branch.store_uncommitted(creator)
+        self.assertIsNot(None, branch.get_unshelver(tree))
+
+    def test_store_uncommitted_bound(self):
+        tree = self.make_branch_and_tree('b')
+        branch = tree.branch
+        master = self.make_branch('master')
+        self.bind(branch, master)
+        creator = FakeShelfCreator(tree.branch)
+        self.assertIs(None, tree.branch.get_unshelver(tree))
+        self.assertIs(None, master.get_unshelver(tree))
+        tree.branch.store_uncommitted(creator)
+        self.assertIsNot(None, master.get_unshelver(tree))
+
+    def test_store_uncommitted_already_stored(self):
+        branch = self.make_branch('b')
+        with skip_if_storing_uncommitted_unsupported():
+            branch.store_uncommitted(FakeShelfCreator(branch))
+        self.assertRaises(errors.ChangesAlreadyStored,
+                          branch.store_uncommitted, FakeShelfCreator(branch))
+
+    def test_store_uncommitted_none(self):
+        branch = self.make_branch('b')
+        with skip_if_storing_uncommitted_unsupported():
+            branch.store_uncommitted(FakeShelfCreator(branch))
+        branch.store_uncommitted(None)
+        self.assertIs(None, branch.get_unshelver(None))
+
+    def test_get_unshelver(self):
+        tree = self.make_branch_and_tree('tree')
+        tree.commit('')
+        self.build_tree_contents([('tree/file', 'contents1')])
+        tree.add('file')
+        with skip_if_storing_uncommitted_unsupported():
+            tree.store_uncommitted()
+        unshelver = tree.branch.get_unshelver(tree)
+        self.assertIsNot(None, unshelver)
+
+    def test_get_unshelver_bound(self):
+        tree = self.make_branch_and_tree('tree')
+        tree.commit('')
+        self.build_tree_contents([('tree/file', 'contents1')])
+        tree.add('file')
+        with skip_if_storing_uncommitted_unsupported():
+            tree.store_uncommitted()
+        branch = self.make_branch('branch')
+        self.bind(branch, tree.branch)
+        unshelver = branch.get_unshelver(tree)
+        self.assertIsNot(None, unshelver)

=== modified file 'bzrlib/tests/test_switch.py'
--- bzrlib/tests/test_switch.py	2011-05-13 12:51:05 +0000
+++ bzrlib/tests/test_switch.py	2012-07-23 17:13:23 +0000
@@ -22,9 +22,11 @@
 from bzrlib import (
     branch,
     errors,
+    lock,
     merge as _mod_merge,
     switch,
     tests,
+    workingtree,
     )
 
 
@@ -34,6 +36,14 @@
         super(TestSwitch, self).setUp()
         self.lightweight = True
 
+    @staticmethod
+    def _master_if_present(branch):
+        master = branch.get_master_branch()
+        if master:
+            return master
+        else:
+            return branch
+
     def _setup_tree(self):
         tree = self.make_branch_and_tree('branch-1')
         self.build_tree(['branch-1/file-1'])
@@ -41,18 +51,56 @@
         tree.commit('rev1')
         return tree
 
+    def _setup_uncommitted(self, same_revision=False):
+        tree = self._setup_tree()
+        to_branch = tree.bzrdir.sprout('branch-2').open_branch()
+        self.build_tree(['branch-1/file-2'])
+        if not same_revision:
+            tree.add('file-2')
+            tree.remove('file-1')
+            tree.commit('rev2')
+        checkout = tree.branch.create_checkout('checkout',
+            lightweight=self.lightweight)
+        self.build_tree(['checkout/file-3'])
+        checkout.add('file-3')
+        return checkout, to_branch
+
+    def test_switch_store_uncommitted(self):
+        """Test switch updates tree and stores uncommitted changes."""
+        checkout, to_branch = self._setup_uncommitted()
+        self.assertPathDoesNotExist('checkout/file-1')
+        self.assertPathExists('checkout/file-2')
+        switch.switch(checkout.bzrdir, to_branch, store_uncommitted=True)
+        self.assertPathExists('checkout/file-1')
+        self.assertPathDoesNotExist('checkout/file-2')
+        self.assertPathDoesNotExist('checkout/file-3')
+
+    def test_switch_restore_uncommitted(self):
+        """Test switch updates tree and restores uncommitted changes."""
+        checkout, to_branch = self._setup_uncommitted()
+        old_branch = self._master_if_present(checkout.branch)
+        self.assertPathDoesNotExist('checkout/file-1')
+        self.assertPathExists('checkout/file-2')
+        self.assertPathExists('checkout/file-3')
+        switch.switch(checkout.bzrdir, to_branch, store_uncommitted=True)
+        checkout = workingtree.WorkingTree.open('checkout')
+        switch.switch(checkout.bzrdir, old_branch, store_uncommitted=True)
+        self.assertPathDoesNotExist('checkout/file-1')
+        self.assertPathExists('checkout/file-2')
+        self.assertPathExists('checkout/file-3')
+
+    def test_switch_restore_uncommitted_same_revision(self):
+        """Test switch updates tree and restores uncommitted changes."""
+        checkout, to_branch = self._setup_uncommitted(same_revision=True)
+        old_branch = self._master_if_present(checkout.branch)
+        switch.switch(checkout.bzrdir, to_branch, store_uncommitted=True)
+        checkout = workingtree.WorkingTree.open('checkout')
+        switch.switch(checkout.bzrdir, old_branch, store_uncommitted=True)
+        self.assertPathExists('checkout/file-3')
+
     def test_switch_updates(self):
         """Test switch updates tree and keeps uncommitted changes."""
-        tree = self._setup_tree()
-        to_branch = tree.bzrdir.sprout('branch-2').open_branch()
-        self.build_tree(['branch-1/file-2'])
-        tree.add('file-2')
-        tree.remove('file-1')
-        tree.commit('rev2')
-        checkout = tree.branch.create_checkout('checkout',
-            lightweight=self.lightweight)
-        self.build_tree(['checkout/file-3'])
-        checkout.add('file-3')
+        checkout, to_branch = self._setup_uncommitted()
         self.assertPathDoesNotExist('checkout/file-1')
         self.assertPathExists('checkout/file-2')
         switch.switch(checkout.bzrdir, to_branch)

=== modified file 'bzrlib/tests/test_workingtree.py'
--- bzrlib/tests/test_workingtree.py	2012-03-14 08:34:10 +0000
+++ bzrlib/tests/test_workingtree.py	2012-07-23 17:13:23 +0000
@@ -19,12 +19,12 @@
     bzrdir,
     conflicts,
     errors,
-    symbol_versioning,
     transport,
     workingtree,
     workingtree_3,
     workingtree_4,
     )
+from bzrlib.lock import write_locked
 from bzrlib.lockdir import LockDir
 from bzrlib.mutabletree import needs_tree_write_lock
 from bzrlib.tests import TestCase, TestCaseWithTransport, TestSkipped
@@ -495,3 +495,34 @@
         self.make_branch('qux')
         trees = workingtree.WorkingTree.find_trees('.')
         self.assertEqual(2, len(list(trees)))
+
+
+class TestStoredUncommitted(TestCaseWithTransport):
+
+    def store_uncommitted(self):
+        tree = self.make_branch_and_tree('tree')
+        tree.commit('get root in there')
+        self.build_tree_contents([('tree/file', 'content')])
+        tree.add('file', 'file-id')
+        tree.store_uncommitted()
+        return tree
+
+    def test_store_uncommitted(self):
+        self.store_uncommitted()
+        self.assertPathDoesNotExist('tree/file')
+
+    def test_store_uncommitted_no_change(self):
+        tree = self.make_branch_and_tree('tree')
+        tree.commit('get root in there')
+        tree.store_uncommitted()
+        self.assertIs(None, tree.branch.get_unshelver(tree))
+
+    def test_restore_uncommitted(self):
+        with write_locked(self.store_uncommitted()) as tree:
+            tree.restore_uncommitted()
+            self.assertPathExists('tree/file')
+            self.assertIs(None, tree.branch.get_unshelver(tree))
+
+    def test_restore_uncommitted_none(self):
+        tree = self.make_branch_and_tree('tree')
+        tree.restore_uncommitted()

=== modified file 'bzrlib/workingtree.py'
--- bzrlib/workingtree.py	2012-06-18 11:43:07 +0000
+++ bzrlib/workingtree.py	2012-07-23 17:13:23 +0000
@@ -60,6 +60,7 @@
     revision as _mod_revision,
     revisiontree,
     rio as _mod_rio,
+    shelf,
     transform,
     transport,
     ui,
@@ -1351,6 +1352,34 @@
                 basis_tree.unlock()
         return conflicts
 
+    @needs_write_lock
+    def store_uncommitted(self):
+        """Store uncommitted changes from the tree in the branch."""
+        target_tree = self.basis_tree()
+        shelf_creator = shelf.ShelfCreator(self, target_tree)
+        try:
+            if not shelf_creator.shelve_all():
+                return
+            self.branch.store_uncommitted(shelf_creator)
+            shelf_creator.transform()
+        finally:
+            shelf_creator.finalize()
+        note('Uncommitted changes stored in branch "%s".', self.branch.nick)
+
+    @needs_write_lock
+    def restore_uncommitted(self):
+        """Restore uncommitted changes from the branch into the tree."""
+        unshelver = self.branch.get_unshelver(self)
+        if unshelver is None:
+            return
+        try:
+            merger = unshelver.make_merger()
+            merger.ignore_zero = True
+            merger.do_merge()
+            self.branch.store_uncommitted(None)
+        finally:
+            unshelver.finalize()
+
     def revision_tree(self, revision_id):
         """See Tree.revision_tree.
 

=== modified file 'doc/en/release-notes/bzr-2.6.txt'
--- doc/en/release-notes/bzr-2.6.txt	2012-07-10 12:19:23 +0000
+++ doc/en/release-notes/bzr-2.6.txt	2012-07-23 17:13:23 +0000
@@ -18,7 +18,8 @@
 New Features
 ************
 
-.. New commands, options, etc that users may wish to try out.
+* ``bzr switch --store`` now stores uncommitted changes in the branch, and
+  restores them when switching back to the branch. (Aaron Bentley)
 
 Improvements
 ************

=== modified file 'doc/en/user-guide/index-plain.txt'
--- doc/en/user-guide/index-plain.txt	2011-05-16 10:22:06 +0000
+++ doc/en/user-guide/index-plain.txt	2012-07-23 17:13:23 +0000
@@ -79,6 +79,7 @@
 .. include:: part2_intro.txt
 .. include:: adv_merging.txt
 .. include:: shelving_changes.txt
+.. include:: switch_store.txt
 .. include:: filtered_views.txt
 .. include:: stacked.txt
 .. include:: server.txt

=== modified file 'doc/en/user-guide/index.txt'
--- doc/en/user-guide/index.txt	2011-06-13 14:08:28 +0000
+++ doc/en/user-guide/index.txt	2012-07-23 17:13:23 +0000
@@ -97,6 +97,7 @@
 
    part2_intro
    adv_merging
+   switch_store
    shelving_changes
    filtered_views
    stacked

=== added file 'doc/en/user-guide/switch_store.txt'
--- doc/en/user-guide/switch_store.txt	1970-01-01 00:00:00 +0000
+++ doc/en/user-guide/switch_store.txt	2012-07-23 17:13:23 +0000
@@ -0,0 +1,93 @@
+Switch --store
+==============
+
+In workflows that a single working tree, like co-located branches, sometimes
+you want to switch while you have uncommitted changes.  By default, ``switch``
+will apply your uncommitted changes to the new branch that you switch to.  But
+often you don't want that.  You just want to do some work in the other branch,
+and eventually return to this branch and work some more.
+
+You could run ``bzr shelve --all`` before switching, to store the changes
+safely.  So you have to know that there are uncommitted changes present, and
+you have to remember to run ``bzr shelve --all``.  Then when you switch back to
+the branch, you need to remember to unshelve the changes, and you need to know
+what their shelf-id was.
+
+Using ``switch --store`` takes care of all of this for you.  If there are any
+uncommitted changes in your tree, it stores them in your branch.  It then
+restores any uncommitted changes that were stored in the branch of your target
+tree.  It's almost like having two working trees and using ``cd`` to switch
+between them.
+
+To take an example, first we'd set up a co-located branch::
+
+  $ bzr init foo
+  Created a standalone tree (format: 2a)
+  $ cd foo
+  $ bzr switch -b foo
+
+Now create committed and uncommitted changes::
+
+  $ touch committed
+  $ bzr add
+  adding committed
+  $ bzr commit -m "Add committed"
+  Committing to: /home/abentley/sandbox/foo/
+  added committed
+  Committed revision 1.
+  $ touch uncommitted
+  $ bzr add
+  adding uncommitted
+  $ ls
+  committed  uncommitted
+
+Now create a new branch using ``--store``.  The uncommitted changes are stored
+in "foo", but the committed changes are retained.
+::
+
+  $ bzr switch -b --store bar
+  Uncommitted changes stored in branch "foo".
+  Tree is up to date at revision 1.
+  Switched to branch: /home/abentley/sandbox/foo/
+  abentley@speedy:~/sandbox/foo$ ls
+  committed
+
+Now, create uncommitted changes in "bar"::
+
+  $ touch uncommitted-bar
+  $ bzr add
+  adding uncommitted-bar
+
+Finally, switch back to "foo"::
+
+  $ bzr switch --store foo
+  Uncommitted changes stored in branch "bar".
+  Tree is up to date at revision 1.
+  Switched to branch: /home/abentley/sandbox/foo/
+  $ ls
+  committed  uncommitted
+
+Each branch holds only one set of stored changes.  If you try to store a second
+set, you get an error.  If you use ``--store`` all the time, this can't happen.
+But if you use plain switch, then it won't restore the uncommitted changes
+already present::
+
+  $ bzr switch bar
+  Tree is up to date at revision 1.
+  Switched to branch: /home/abentley/sandbox/foo/
+  $ bzr switch --store foo
+  bzr: ERROR: Cannot store uncommitted changes because this branch already
+  stores uncommitted changes.
+
+If you're working in a branch that already has stored changes, you can restore
+them with ``bzr switch . --store``::
+
+  $ bzr shelve --all -m "Uncommitted changes from foo"
+  Selected changes:
+  -D  uncommitted
+  Changes shelved with id "1".
+  $ bzr switch . --store
+  Tree is up to date at revision 1.
+  Switched to branch: /home/abentley/sandbox/foo/
+  $ ls
+  committed  uncommitted-bar