Rev 3551: (mbp) further stacking tweaks in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Thu Jul 17 07:45:05 BST 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3551
revision-id:pqm at pqm.ubuntu.com-20080717064451-za459i23yr9zwbul
parent: pqm at pqm.ubuntu.com-20080717061742-zs1bj4n2m7qnzoaf
parent: mbp at sourcefrog.net-20080717060008-ulu4d4h8b57604yb
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2008-07-17 07:44:51 +0100
message:
(mbp) further stacking tweaks
added:
doc/en/user-guide/stacked.txt stacked.txt-20080711023247-4uh9oovoka0sze8b-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/builtins.py builtins.py-20050830033751-fc01482b9ca23183
bzrlib/push.py push.py-20080606021927-5fe39050e8xne9un-1
bzrlib/tests/blackbox/test_push.py test_push.py-20060329002750-929af230d5d22663
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
------------------------------------------------------------
revno: 3549.1.3
revision-id:mbp at sourcefrog.net-20080717060008-ulu4d4h8b57604yb
parent: mbp at sourcefrog.net-20080717055343-63e9iylwcxxeg8hx
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: stacking
timestamp: Thu 2008-07-17 16:00:08 +1000
message:
Review comments to stacking operations
modified:
doc/en/user-guide/stacked.txt stacked.txt-20080711023247-4uh9oovoka0sze8b-1
------------------------------------------------------------
revno: 3549.1.2
revision-id:mbp at sourcefrog.net-20080717055343-63e9iylwcxxeg8hx
parent: mbp at sourcefrog.net-20080717055129-pc3im88b6aou5fv4
parent: ian.clatworthy at canonical.com-20080711023329-0p2migiydrfqsz0t
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: stacking
timestamp: Thu 2008-07-17 15:53:43 +1000
message:
Merge stacking user documentation
added:
doc/en/user-guide/stacked.txt stacked.txt-20080711023247-4uh9oovoka0sze8b-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
------------------------------------------------------------
revno: 3535.3.1
revision-id:ian.clatworthy at canonical.com-20080711023329-0p2migiydrfqsz0t
parent: pqm at pqm.ubuntu.com-20080709135859-wq3r1d1fjcafelgw
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.ug-stacked
timestamp: Fri 2008-07-11 12:33:29 +1000
message:
Add user doc for stacked branches
added:
doc/en/user-guide/stacked.txt stacked.txt-20080711023247-4uh9oovoka0sze8b-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
------------------------------------------------------------
revno: 3549.1.1
revision-id:mbp at sourcefrog.net-20080717055129-pc3im88b6aou5fv4
parent: pqm at pqm.ubuntu.com-20080717023455-idnyms69oiauf7fh
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: stacking
timestamp: Thu 2008-07-17 15:51:29 +1000
message:
rename push --reference to --stacked-on
modified:
bzrlib/builtins.py builtins.py-20050830033751-fc01482b9ca23183
bzrlib/push.py push.py-20080606021927-5fe39050e8xne9un-1
bzrlib/tests/blackbox/test_push.py test_push.py-20060329002750-929af230d5d22663
=== added file 'doc/en/user-guide/stacked.txt'
--- a/doc/en/user-guide/stacked.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/user-guide/stacked.txt 2008-07-17 06:00:08 +0000
@@ -0,0 +1,85 @@
+Using stacked branches
+======================
+
+What is a stacked branch?
+-------------------------
+
+A stacked branch is a branch that knows how to find revisions
+in another branch. Stacked branches store just the
+unique revisions, making them faster to create and more
+storage efficient. In these respects, stacked branches are
+similar to shared repositories. However, stacked branches have
+additional benefits:
+
+* The new branch can be in a completely different location to the
+ branch being stacked on.
+
+* Deleting the stacked branch really deletes the revisions (rather
+ than leaving them in a shared repository).
+
+* Security is improved over shared repositories, because the stacked-on
+ repository can be physically readonly to developers committing to stacked
+ branches.
+
+These benefits make stacked branches ideal for various scenarios
+including experimental branches and code hosting sites.
+
+
+Creating a stacked branch
+-------------------------
+
+To create a stacked branch, use the ``stacked`` option of the branch command.
+For example::
+
+ bzr branch --stacked source-url my-dir
+
+This will create ``my-dir`` as a stacked branch with no local revisions.
+If it is defined, the public branch associated with ``source-url`` will be
+used as the *stacked-on* location. Otherwise, ``source-url`` will be the
+*stacked-on* location.
+
+
+Creating a stacked checkout
+---------------------------
+
+Direct creation of a stacked checkout is expected to be supported soon.
+In the meantime, a two step process is required:
+
+1. Create a stacked branch as shown above.
+
+2. Convert the branch into a checkout using either the ``reconfigure``
+ or ``bind`` command.
+
+
+Pushing a stacked branch
+------------------------
+
+Most changes on most projects build on an existing branch such as the
+*development trunk* or *current stable* branch. Creating a new
+branch stacked on one of these is easy to do using the ``push``
+command like this::
+
+ bzr push --stacked-on reference-url my-url
+
+This creates a new branch at ``my-url`` that is stacked on ``reference-url``
+and only contains the revisions in the current branch that are not already
+in the branch at ``reference-url``.
+
+If the local branch was created as a stacked branch, then you can
+use the ``--stacked`` option to ``push`` and the *stacked-on* location
+will be implicit. For example::
+
+ bzr branch --stacked source-url my-dir
+ cd my-dir
+ (hack, hack, hack)
+ bzr commit -m "fix bug"
+ bzr push --stacked
+
+
+Limitations of stacked branches
+-------------------------------
+
+The important thing to remember about a stacked branch is that the
+stacked-on branch needs to be available for almost all operations. This is
+not an issue when both branches are local or both branches are on the
+same server.
=== modified file 'NEWS'
--- a/NEWS 2008-07-17 06:17:42 +0000
+++ b/NEWS 2008-07-17 06:44:51 +0000
@@ -109,6 +109,9 @@
DOCUMENTATION:
+ * Added *Using stacked branches* to the User Guide.
+ (Ian Clatworthy)
+
* Updated developer documentation.
(Martin Pool)
=== modified file 'bzrlib/builtins.py'
--- a/bzrlib/builtins.py 2008-07-17 02:02:35 +0000
+++ b/bzrlib/builtins.py 2008-07-17 05:51:29 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2004, 2005, 2006, 2007 Canonical Ltd
+# Copyright (C) 2004, 2005, 2006, 2007, 2008 Canonical Ltd
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@@ -721,21 +721,22 @@
' directory exists, but does not already'
' have a control directory. This flag will'
' allow push to proceed.'),
- Option('reference',
+ Option('stacked',
+ help='Create a stacked branch that references the public location '
+ 'of the parent branch.'),
+ Option('stacked-on',
help='Create a stacked branch that refers to another branch '
'for the commit history. Only the work not present in the '
'referenced branch is included in the branch created.',
type=unicode),
- Option('stacked',
- help='Create a stacked branch that references the public location '
- 'of the parent branch. See --reference for more information.'),
]
takes_args = ['location?']
encoding_type = 'replace'
def run(self, location=None, remember=False, overwrite=False,
create_prefix=False, verbose=False, revision=None,
- use_existing_dir=False, directory=None, reference=None, stacked=False):
+ use_existing_dir=False, directory=None, stacked_on=None,
+ stacked=False):
from bzrlib.push import _show_push_branch
# Get the source branch and revision_id
@@ -751,22 +752,21 @@
else:
revision_id = br_from.last_revision()
- # Get the reference branch, if any
- if reference is not None:
- reference = urlutils.normalize_url(reference)
+ # Get the stacked_on branch, if any
+ if stacked_on is not None:
+ stacked_on = urlutils.normalize_url(stacked_on)
elif stacked:
- reference = None
parent_url = br_from.get_parent()
if parent_url:
parent = Branch.open(parent_url)
- reference = parent.get_public_branch()
- if not reference:
+ stacked_on = parent.get_public_branch()
+ if not stacked_on:
# I considered excluding non-http url's here, thus forcing
# 'public' branches only, but that only works for some
# users, so it's best to just depend on the user spotting an
# error by the feedback given to them. RBC 20080227.
- reference = parent_url
- if not reference:
+ stacked_on = parent_url
+ if not stacked_on:
raise errors.BzrCommandError(
"Could not determine branch to refer to.")
@@ -784,7 +784,7 @@
_show_push_branch(br_from, revision_id, location, self.outf,
verbose=verbose, overwrite=overwrite, remember=remember,
- reference=reference, create_prefix=create_prefix,
+ stacked_on=stacked_on, create_prefix=create_prefix,
use_existing_dir=use_existing_dir)
=== modified file 'bzrlib/push.py'
--- a/bzrlib/push.py 2008-07-15 05:18:31 +0000
+++ b/bzrlib/push.py 2008-07-17 05:51:29 +0000
@@ -21,7 +21,7 @@
def _show_push_branch(br_from, revision_id, location, to_file, verbose=False,
- overwrite=False, remember=False, reference=None, create_prefix=False,
+ overwrite=False, remember=False, stacked_on=None, create_prefix=False,
use_existing_dir=False):
"""Push a branch to a location.
@@ -34,7 +34,7 @@
have diverged from the source, otherwise the push fails
:param remember: if True, store the location as the push location for
the source branch
- :param reference: the url of the branch, if any, to stack on;
+ :param stacked_on: the url of the branch, if any, to stack on;
if set, only the revisions not in that branch are pushed
:param create_prefix: if True, create the necessary parent directories
at the destination if they don't already exist
@@ -101,7 +101,7 @@
# Now the target directory exists, but doesn't have a .bzr
# directory. So we need to create it, along with any work to create
# all of the dependent branches, etc.
- if reference is not None:
+ if stacked_on is not None:
# This should be buried in the clone method itself. TODO.
try:
# if the from format is stackable, this will either work or
@@ -114,7 +114,7 @@
dir_to = br_from.bzrdir._format.initialize_on_transport(to_transport)
br_from.repository._format.initialize(dir_to)
br_to = br_from._format.initialize(dir_to)
- br_to.set_stacked_on_url(reference)
+ br_to.set_stacked_on_url(stacked_on)
# and copy the data up.
br_from.push(br_to)
else:
@@ -122,8 +122,8 @@
revision_id=revision_id)
br_to = dir_to.open_branch()
# TODO: Some more useful message about what was copied
- if reference is not None:
- note('Created new stacked branch referring to %s.' % reference)
+ if stacked_on is not None:
+ note('Created new stacked branch referring to %s.' % stacked_on)
else:
note('Created new branch.')
# We successfully created the target, remember it
@@ -140,7 +140,7 @@
elif br_to is None:
# We have a repository but no branch, copy the revisions, and then
# create a branch.
- if reference is not None:
+ if stacked_on is not None:
warning("Ignoring request for a stacked branch as repository "
"already exists at the destination location.")
repository_to.fetch(br_from.repository, revision_id=revision_id)
@@ -149,7 +149,7 @@
if br_from.get_push_location() is None or remember:
br_from.set_push_location(br_to.base)
else: # We have a valid to branch
- if reference is not None:
+ if stacked_on is not None:
warning("Ignoring request for a stacked branch as branch "
"already exists at the destination location.")
# We were able to connect to the remote location, so remember it.
=== modified file 'bzrlib/tests/blackbox/test_push.py'
--- a/bzrlib/tests/blackbox/test_push.py 2008-07-16 07:30:18 +0000
+++ b/bzrlib/tests/blackbox/test_push.py 2008-07-17 05:51:29 +0000
@@ -1,4 +1,4 @@
-# Copyright (C) 2005, 2007 Canonical Ltd
+# Copyright (C) 2005, 2007, 2008 Canonical Ltd
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@@ -289,11 +289,11 @@
# and the branch's work was pushed
self.assertTrue(published_branch.repository.has_revision(branch_revid))
- def test_push_new_branch_reference(self):
- """Pushing a new branch with --reference creates a stacked branch."""
+ def test_push_new_branch_stacked_on(self):
+ """Pushing a new branch with --stacked-on creates a stacked branch."""
trunk_tree, branch_tree = self.create_trunk_and_feature_branch()
# we publish branch_tree with a reference to the mainline.
- out, err = self.run_bzr(['push', '--reference', trunk_tree.branch.base,
+ out, err = self.run_bzr(['push', '--stacked-on', trunk_tree.branch.base,
self.get_url('published')], working_dir='branch')
self.assertEqual('', out)
self.assertEqual('Created new stacked branch referring to %s.\n' %
=== modified file 'doc/en/user-guide/index.txt'
--- a/doc/en/user-guide/index.txt 2008-06-06 12:02:48 +0000
+++ b/doc/en/user-guide/index.txt 2008-07-11 02:33:29 +0000
@@ -81,6 +81,7 @@
.. include:: part2_intro.txt
.. include:: adv_merging.txt
+.. include:: stacked.txt
.. include:: server.txt
.. include:: hooks.txt
.. include:: version_info.txt
More information about the bazaar-commits
mailing list