11
This document describes a possible workflow for using Bazaar_. That of
12
using Bazaar_, the distributed version control system, in a centralized
13
manner. Bazaar_ is designed to be very flexible and allows several
14
different workflows, from fully decentralized to mostly centralized. The
15
workflow used here is meant to ease a new user into more advanced usage of
16
Bazaar_, and allow them to work in a mix of centralized and decentralized
19
In general, this document is meant for users coming from a background of
20
centralized version control systems such as CVS or subversion. It is
21
common in work settings to have a single central server hosting the
22
codebase, with several people working on this codebase, keeping their work
23
in sync. This workflow is also applicable to a single developer working
24
on several different machines.
26
.. _Bazaar: http://bazaar-vcs.org
34
These are some reasonably simple steps to setup Bazaar_ so that it works
41
Your user identity is stored with each commit. While this doesn't have to
42
be accurate or unique, it will be used in log messages and
43
annotations, so it is better to have something real.
47
% bzr whoami "John Doe <jdoe@organization.com>"
50
Setting up a local Repository
51
-----------------------------
53
Bazaar_ branches generally copy the history information around with them,
54
which is part of how you can work in a fully decentralized manner. As an
55
optimization, it is possible for related branches to combine their storage
56
needs so that you do not need to copy around all of this history
57
information whenever you create a new branch.
59
The best way to do this is to create a `Shared Repository`_. In
60
general, branches will share their storage if they exist in a
61
subdirectory of a `Shared Repository`_. So let's set up a `Shared
62
Repository`_ in our home directory, thus all branches we create
63
underneath will share their history storage.
67
% bzr init-repo --trees ~
70
Setting up a remote Repository
71
---------------------------------
73
Many times you want a location where data is stored separately from where
74
you do your work. This workflow is required by centralized systems
75
(CVS/SVN). Usually they are on separate machines, but not always. This is
76
actually a pretty good setup, especially in a work environment. Since it
77
ensures a central location where data can be backed up, and means that if
78
something happens to a developer's machine, no committed work has to be
81
So let's set up a shared location for our project on a remote machine
82
called ``centralhost``. Again, we will use a
83
`Shared Repository`_ to optimize disk usage.
87
% bzr init-repo --no-trees sftp://centralhost/srv/bzr/
89
You can think of this step as similar to setting up a new cvsroot, or
90
subversion repository. The {{{--no-trees}}} option tells bzr to not
91
populate the directory with a working tree. This is appropriate,
92
since no one will be making changes directly in the branches within
93
the central repository.
96
Migrating an existing project to Bazaar
97
=======================================
99
Now that we have a repository, let's create a versioned project. Most of
100
the time, you will already have some code that you are working with,
101
that you now want to version using Bazaar_. If the code was originally
102
in source control, there are many ways to convert the project to Bazaar_
103
without losing any history. However, this is outside the scope of this
104
document. See `Tracking Upstream`_ for some possibilities (section
105
"Converting and keeping history").
107
.. _Tracking Upstream: http://bazaar-vcs.org/TrackingUpstream
110
XXX: We really need a different document for discussing conversion of a
111
project. Right now TrackingUpstream is the best we have, though.
114
Developer 1: Creating the first revision
115
----------------------------------------
117
So first, we want to create a branch in our remote Repository, where we
118
want to host the project. Let's assume we have a project named
119
"sigil" that we want to put under version control.
123
% bzr init sftp://centralhost/srv/bzr/sigil
125
This can be thought of as the "HEAD" branch in CVS terms, or as the "trunk"
126
in Subversion terms. We will call this the ``dev`` branch.
128
I prefer working in a subdirectory of my home directory to avoid collisions with all
129
the other files that end up there. Also, we will want a project
130
directory where we can hold all of the different branches we end up
140
% bzr checkout sftp://centralhost/srv/bzr/sigil dev
144
% bzr commit -m "Initial import of Sigil"
147
In the previous section, we created an empty branch (the ``/sigil``
148
branch) on ``centralhost``, and then checkout out this empty branch
149
onto our workstation to add files from our existing project. There
150
are many ways to set up your working directory, but the steps above
151
make it easy to handle working with feature/bugfix branches. And one
152
of the strong points of Bazaar_ is how well it works with branches.
154
At this point, because you have a 'checkout' of the remote branch, any
155
commits you make in ``~/work/sigil/dev/`` will automatically be saved
156
both locally, and on ``centralhost``.
159
Developer N: Getting a working copy of the project
160
--------------------------------------------------
162
Since the first developer did all of the work of creating the project,
163
all other developers would just checkout that branch. **They should
164
still follow** `Setting User Email`_ and `Setting up a local Repository`_.
166
To get a copy of the current development tree::
169
% bzr checkout sftp://centralhost/srv/bzr/sigil dev
171
Now that two people both have a checkout of
172
``sftp://centralhost/srv/bzr/sigil``, there will be times when one of
173
the checkouts will be out of date with the current version.
174
At commit time, Bazaar_ will inform the user of this and prevent them from
175
committing. To get up to date, use ``bzr update`` to update the
176
tree with the remote changes. This may require resolving conflicts if the
177
same files have been modified.
180
Developing on separate branches
181
===============================
183
So far everyone is working and committing their changes into the same
184
branch. This means that everyone needs to update fairly regularly and
185
deal with other people's changes. Also, if one person commits something
186
that breaks the codebase, then upon syncing, everyone will get the
189
Usually, it is better to do development on different branches, and then
190
integrate those back into the main branch, once they are stable. This is
191
one of the biggest changes from working with CVS/SVN. They both allow you
192
to work on separate branches, but their merging algorithms are fairly
193
weak, so it is difficult to keep things synchronized. Bazaar_ tracks
194
what has already been merged, and can even apply changes to files that
198
Creating and working on a new branch
199
------------------------------------
201
We want to keep our changes available for other people, even if they
202
aren't quite complete yet. So we will create a new public branch on
203
``centralhost``, and track it locally.
208
% bzr branch sftp://centralhost/srv/bzr/sigil \
209
sftp://centralhost/srv/bzr/sigil/doodle-fixes
210
% bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes
213
We now have a place to make any fixes we need to ``doodle``. And we would
214
not interrupt people who are working on other parts of the code. Because
215
we have a checkout, any commits made in the ``~/work/sigil/doodle-fixes/``
216
will also show up on ``centralhost``. [#nestedbranches]_ It is also
217
possible to have two developers collaborate on one of these branches, just
218
like they would have collaborated on the ``dev`` branch. [#cbranch]_
220
.. [#nestedbranches] It may look odd to have a branch in a subdirectory of
221
another branch. This is just fine, and you can think of it as a
222
hierarchical namespace where the nested branch is derived from the
225
.. [#cbranch] When using lots of independent branches, having to retype
226
the full URL all the time takes a lot of typing. We are looking into
227
various methods to help with this, such as branch aliases, etc. For
228
now, though, the bzrtools_ plugin provides the ``bzr cbranch`` command.
229
Which is designed to take a base branch, create a new public branch,
230
and create a checkout of that branch, all with much less typing.
231
Configuring ``cbranch`` is outside the scope of this document, but the
232
final commands are similar to:
236
% bzr cbranch dev my-feature-branch
238
.. _bzrtools: https://launchpad.net/products/bzrtools
244
When it is decided that some of the changes in ``doodle-fixes`` are ready
245
to be merged into the main branch, simply do::
247
% cd ~/work/sigil/dev
248
% bzr merge ../doodle-fixes
250
Now the changes are available in the ``dev`` branch, but they have not
251
been committed yet. This is the time when you want to review the final
252
changes, and double check the code to make sure it compiles cleanly and
253
passes the test suite. The commands ``bzr status`` and ``bzr diff`` are
254
good tools to use here. Also, this is the time to resolve any conflicts.
255
Bazaar_ will prevent you from committing until you have resolved these
256
conflicts. That way you don't accidentally commit the conflict markers.
257
The command ``bzr status`` will show the conflicts along with the other
258
changes, or you can use ``bzr conflicts`` to just list conflicts. Use
259
``bzr resolve file/name`` or ``bzr resolve --all`` once conflicts have
260
been handled. [#resolve]_ If you have a conflict that is particularly
261
difficult to solve you may want to use the ``bzr remerge`` command. It
262
will let you try different merge algorithms, as well as let you see the
263
original source lines (``--show-base``).
265
.. [#resolve] Some systems make you resolve conflicts as part of the merge
266
process. We have found that it is usually easier to resolve conflicts
267
when you have the view of the entire tree, rather than just a single
268
file. It gives you much more context, and also lets you run tests as
269
you resolve the problems.
272
Recommended Branching
273
---------------------
275
One very common way to handle all of these branches is to give each
276
developer their own branch, and their own place to work in the central
277
location. This can be done with::
279
% bzr branch sftp://centralhost/srv/bzr/sigil \
280
sftp://centralhost/srv/bzr/sigil/user-a
281
% bzr branch sftp://centralhost/srv/bzr/sigil \
282
sftp://centralhost/srv/bzr/sigil/user-b
284
This gives each developer their own branch to work on. And, they can
285
easily create a new feature branch for themselves with just [#cbranch]_
288
% bzr branch sftp://centralhost/srv/bzr/sigil/user-a \
289
sftp://centralhost/srv/bzr/sigil/user-a/feature
291
% bzr checkout sftp://centralhost/srv/bzr/sigil/user-a/feature myfeature
300
Bazaar_ has the concept of a "Shared Repository". This is similar to
301
the traditional concept of a repository in other RCSs like CVS and
302
Subversion. For example, in Subversion you have a remote repository,
303
which is where all of the history is stored, and locally you don't
304
have any history information, only a checkout of the working tree
305
files. Note that "Shared" in this context means shared between
306
branches. It *may* be shared between people, but standalone branches
307
can also be shared between people.
309
In Bazaar_ terms, a "Shared Repository" is a location where multiple
310
branches can **share** their revision history information. In order to
311
support decentralized workflows, it is possible for every branch to
312
store its own revision history information. But this is often
313
inefficient, since related branches share history, and they might as
314
well share the storage as well.
318
vim: tw=74 ft=rst spell spelllang=en_us
added
removed
doc/centralized_workflow.txt
