1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
Organizing your workspace
=========================
Common workspace layouts
------------------------
The best way for a Bazaar user to organize their workspace for a project
depends on numerous factors including:
* user role: project owner vs core developer vs casual contributor
* workflows: particularly the workflow the project encourages/mandates
for making contributions
* size: large projects have different resource requirements to small ones.
There are at least 4 common ways of organizing one's workspace:
* lightweight checkout
* standalone tree
* feature branches
* switchable sandbox.
A brief description of each layout follows.
Lightweight checkout
--------------------
In this layout, the working tree is local and the branch is remote.
This is the standard layout used by CVS and Subversion: it's simple
and well understood.
To set up::
bzr checkout --lightweight URL project
cd project
To work::
(make changes)
bzr commit
(make changes)
bzr commit
Note that each commit implicitly publishes the change to everyone else
working from that branch. However, you need to be up to date with changes
in the remote branch for the commit to succeed. To grab the latest code
and merge it with your changes, if any::
bzr update
Standalone tree
---------------
In this layout, the working tree & branch are in the one place. Unless
a shared repository exists in a higher level directory, the repository
is located in that same place as well. This is the default layout in
Bazaar and it's great for small to moderately sized projects.
To set up::
bzr branch URL project
cd project
To work::
(make changes)
bzr commit
(make changes)
bzr commit
To publish changes to a central location::
bzr push [URL]
The URL for push is only required the first time.
If the central location has, in the meantime, received changes from
other users, then you'll need to merge those changes into your local
branch before you try to push again::
bzr merge
(resolve conflicts)
bzr commit
As an alternative, a checkout can be used. Like a branch, a checkout
has a full copy of the history stored locally but the local branch
is bound to the remote location so that commits are published to
both locations at once.
Note: A checkout is actually smarter than a local commit followed by
a push. In particular, a checkout wil commit to the remote location
first and only commit locally if the remote commit succeeds.
Feature branches
----------------
In this layout, there are multiple branches/trees, typically sharing
a repository. One branch is kept as a mirror of "trunk" and each
unit-of-work (i.e. bug-fix or enhancement) gets its own "feature branch".
This layout is ideal for most projects, particularly moderately sized ones.
To set up::
bzr init-repo project
cd project
bzr branch URL trunk
To start a feature branch::
bzr branch trunk featureX
cd featureX
To work::
(make changes)
bzr commit
(make changes)
bzr commit
To publish changes to a mailing list for review & approval::
bzr send
To publish changes to a public branch (that can then be registered as
a Launchpad merge request, say)::
bzr push [URL]
As a variation, the trunk can be created as a checkout. If you have
commit privileges on trunk, that lets you merge into trunk and the
commit of the merge will implicitly publish your change. Alternatively,
if the trunk URL is read-only (e.g. an HTTP address), that prevents
accidental submission this way - ideal if the project workflow uses
an automated gatekeeper like PQM, say.
Local sandbox
-------------
This layout is very similar to the feature branches layout except that
the feature branches share a single working tree rather than having one
each. This is similar to git's default layout and it's useful for projects
with really large trees (> 10000 files say) or for projects with lots of
build artifacts (like .o or .class files).
To set up::
bzr init-repo --no-trees project
cd project
bzr branch URL trunk
bzr checkout --lightweight trunk sandbox
cd sandbox
While you *could* start making changes in sandbox now, committing while
the sandbox is pointing to the trunk would mean that trunk is no longer
a mirror of the upstream URL (well unless the trunk is a checkout).
Therefore, you usually want to immediately create a feature branch and
switch your sandbox to it like this::
bzr branch ../trunk ../featureX
bzr switch ../featureX
The processes for making changes and submitting them are otherwise
pretty much the same as those used for feature branches.
Advanced layouts
----------------
If you wish, you can put together your own layout based on how **you** like
things organized. See `Advanced shared repository layouts
<shared_repository_layouts.html>`_ for examples and inspiration.
|