← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/colocated-branches.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-09-29 22:03:03 UTC
  • mfrom: (5416.2.6 jam-integration)
  • Revision ID: pqm@pqm.ubuntu.com-20100929220303-cr95h8iwtggco721
(mbp) Add 'break-lock --force'

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/colocated-branches.txt
 
1
co-located branches
 
2
===================
 
3
 
 
4
At the moment, each Bazaar branch has a separate directory in the file
 
5
system. While this works well, and makes it very easy to discover
 
6
branches there are several situations where it might be useful to also
 
7
support multiple branches under the same file system directory.
 
8
 
 
9
Rationale
 
10
---------
 
11
 
 
12
Allowing multiple branches to live under the same directory in the file
 
13
system means that it is possible to very easily share the same working
 
14
tree and repository between those branches, without having a lot of fs
 
15
infrastructure.
 
16
 
 
17
Git and Mercurial (can) store multiple branches under a single directory
 
18
in the file system - per repository, so to speak. In order for this to
 
19
be accessible in Bazaar, Bazaar needs to have the right APIs and UI for
 
20
accessing these branches.
 
21
 
 
22
Use Cases
 
23
---------
 
24
 
 
25
Carla has a large C-based project with a large tree and a lot of .o
 
26
files that get generated as part of her build process. She doesn't want
 
27
to create a new working tree for each new branch but simply uses "bzr
 
28
switch" to switch between the different colocated branches that all use
 
29
the same working tree.
 
30
 
 
31
Brad has a single project with a lot of related branches. He works on
 
32
them and occasionally pushes all of those branches to a remote host
 
33
using a single push command.
 
34
 
 
35
Joe follows one of his co-workers local branches in Mercurial by pulling
 
36
into Bazaar.
 
37
 
 
38
Implementation
 
39
--------------
 
40
 
 
41
UI Changes
 
42
~~~~~~~~~~
 
43
 
 
44
Bazaar URLs need to have some way to address colocated branches in 
 
45
directories that contain multiple branches. 
 
46
 
 
47
Per RFC3986 we have picked the comma (",") to allow the specification of 
 
48
colocated branch names. Comma's in path names would have to be 
 
49
urlencoded at first to avoid ambiguity, though perhaps it would be 
 
50
possible to support heuristics later when interpreting user-specified URLs.
 
51
 
 
52
An example URL would be:
 
53
 
 
54
 bzr://bazaar.launchpad.net/~jelmer/bzr/bzr.dev,colo-urls
 
55
 
 
56
The segment after the comma will initially be interpreted as a colocated 
 
57
branch name but we would like to keep the option to allow 
 
58
key=value style specifications in the future and DWIM for segments that 
 
59
do not contain an =. Following the RFC the comma would be interpreted within
 
60
the scope of a path segment. In other words, in the URL:
 
61
 
 
62
 git://git.debian.org/pkg-python-debian/python-debian.git,unstable/README
 
63
 
 
64
unstable is interpreted as the colocated branch living in the python-debian.git
 
65
control directory; README is a path inside of the branch.
 
66
 
 
67
Control directories will also have the notion of an "active" branch. This is 
 
68
the branch that is being used by a working tree, if present and the branch 
 
69
that will be used if no explicit colocated branch is specified. The 
 
70
active branch support makes it easier to deal with existing bzrdirs and 
 
71
is useful when accessing foreign control directories that have the concept 
 
72
as well.
 
73
 
 
74
A new command 'bzr rmbranch' needs to be added to make it possible to 
 
75
remove colocated branches, as this won't be possible by simple 
 
76
directory removal, at least not of a user-visible directory.
 
77
 
 
78
Code Changes
 
79
~~~~~~~~~~~~
 
80
 
 
81
BzrDirFormat will need a supports_colocated_branches property that 
 
82
indicates whether a format supports the creation, removal and accessing of 
 
83
colocated branches.
 
84
 
 
85
Several methods on BzrDir will need to be updated to take an option branch_name 
 
86
parameter. If this parameter is not specified or None, the active branch 
 
87
will be used.
 
88
 
 
89
The methods that will have to be extended are:
 
90
 
 
91
 * BzrDir.open_branch()
 
92
 * BzrDir.create_branch()
 
93
 * BzrDir.destroy_branch()
 
94
 * BzrDir.get_branch_transport()
 
95
 
 
96
 * BranchFormat.initialise()
 
97
 * BranchFormat.open()
 
98
 
 
99
A new BzrDir.list_branches() method will return all colocated branches 
 
100
present in a control directory. 
 
101
 
 
102
Any URL interpreting methods (e.g. Branch.open) will need to be updated 
 
103
to extract a colocated branch name and need to pass that into the 
 
104
relevant methods.
 
105
 
 
106
Existing callers of BzrDir.{create,open,destroy}_branch() need to 
 
107
be updated to pass in branch names and optionally be changed to use 
 
108
BzrDir.list_branches().
 
109
 
 
110
Schema Changes
 
111
--------------
 
112
 
 
113
No format changes are necessary at first; at least, even if Bazaar
 
114
provides the right infrastructure it doesn't have to support this
 
115
feature in its own file formats.
 
116
 
 
117
Eventually, Bazaar could easily support colocated branches by just
 
118
creating a new branch transport for each colocated branch and have a
 
119
"regular" branch live there. This would require something like
 
120
BzrDirMeta2 though. An example of this is implemented in the 
 
121
lp:bzr-colocated plugin
 
122
 
 
123
Further integration
 
124
-------------------
 
125
 
 
126
Loggerhead and Launchpad need to be updated to show colocated branches
 
127
(perhaps in a similar way as they would show tags?).
 
128
 
 
129
qbzr/bzr-gtk need to be updated to support colocated branches.