1
=============================
2
Centralized Workflow Tutorial
3
=============================
9
This document describes a possible workflow for using Bazaar_. That of
10
using Bazaar_, the distributed version control system, in a centralized
11
manner. Bazaar_ is designed to be very flexible and allows several
12
different workflows, from fully decentralized to mostly centralized. The
13
workflow used here is meant to ease a new user into more advanced usage of
14
Bazaar_, and allow them to work in a mix of centralized and decentralized
8
This document describes some basic workflow for using Bazaar_. This doesn't
9
try to explain *why* every step is done, but more gives recommendations
10
about what is considered a good way to work with Bazaar_.
11
Bazaar_ is designed to be very flexible in workflows, from fully
12
decentralized to mostly centralized.
13
The practices here are meant to help ease the user into more advanced usage
14
of Bazaar_, and allowing them to work in a mix of centralized and
15
decentralized operation.
17
In general, this document is meant for users coming from a background of
18
centralized version control systems such as CVS or subversion. It is
19
common in work settings to have a single central server hosting the
20
codebase, with several people working on this codebase, keeping their work
21
in sync. This workflow is also applicable to a single developer working
22
on several different machines.
17
In general, this document is meant for people in a work setting. Where
18
several people are working on the same codebase, and want to work with
19
eachother and keep in sync. However, this workflow is also applicable to a
20
single developer, who might work on several machines, and wants to keep in
24
23
.. _Bazaar: http://bazaar-vcs.org
49
46
Bazaar_ branches generally copy the history information around with them,
50
47
which is part of how you can work in a fully decentralized manner. As an
51
optimization, it is possible for related branches to combine their storage
52
needs so that you do not need to copy around all of this history
53
information whenever you create a new branch.
55
The best way to do this is to create a `Shared Repository`_. In
56
general, branches will share their storage if they exist in a
57
subdirectory of a `Shared Repository`_. So let's set up a `Shared
58
Repository`_ in our home directory, thus all branches we create
59
underneath will share their history storage.
48
optimization, it is possible for branches to combine their storage needs,
49
so that you do not need to copy around all of this history information
50
whenever you create a new branch.
52
The best way to do this is to create a `Shared Repository`_. In general,
53
branches will share their storage if they exist in a subdirectory of a
54
`Shared Repository`_. So lets setup a `Shared Repository`_ in our home
55
directory, thus all branches we create underneath will share their history
63
58
% bzr init-repo --trees ~
66
61
Setting up a remote Repository
67
---------------------------------
69
Many times you want a location where data is stored separately from where
70
you do your work. This workflow is required by centralized systems
71
(CVS/SVN). Usually they are on separate machines, but not always. This is
72
actually a pretty good setup, especially in a work environment. Since it
73
ensures a central location where data can be backed up, and means that if
74
something happens to a developer's machine, no committed work has to be
77
So let's set up a shared location for our project on a remote machine
78
called ``centralhost``. Again, we will use a
79
`Shared Repository`_ to optimize disk usage.
62
------------------------------
64
Many times you want a location where data is stored separate from where
65
you do your work. This workflow is required by centralized systems (CVS/SVN).
66
Usually they are on separate machines, but not always. This is actually a
67
pretty good setup, especially in a work environment. Because it ensures
68
a central location where data can be backed up, and means that if something
69
happens to a developer's machine, no committed work has been lost.
71
So lets set up a shared location for our project. Again, we will use a
72
`Shared Repository`_ to optimize disk usage.::
83
74
% bzr init-repo --no-trees sftp://centralhost/srv/bzr/
85
76
You can think of this step as similar to setting up a new cvsroot, or
86
subversion repository. The ``--no-trees`` option tells bzr to not
87
populate the directory with a working tree. This is appropriate,
88
since no one will be making changes directly in the branches within
89
the central repository.
92
Migrating an existing project to Bazaar
77
subversion repository (only obviously it is a little bit simpler).
80
Starting to version an existing project
93
81
=======================================
95
Now that we have a repository, let's create a versioned project. Most of
96
the time, you will already have some code that you are working with,
83
Now that we have a repository, lets get going with a new project. Most of
84
the time, you will already have some code that you started working with,
97
85
that you now want to version using Bazaar_. If the code was originally
98
86
in source control, there are many ways to convert the project to Bazaar_
99
without losing any history. However, this is outside the scope of this
100
document. See `Tracking Upstream`_ for some possibilities (section
101
"Converting and keeping history").
103
.. _Tracking Upstream: http://bazaar-vcs.org/TrackingUpstream
106
XXX: We really need a different document for discussing conversion of a
107
project. Right now TrackingUpstream is the best we have, though.
87
without losing any history. However, this is outside of the scope of this
88
document. See XXXReferenceConversionOfHistory_.
110
91
Developer 1: Creating the first revision
111
92
----------------------------------------
113
94
So first, we want to create a branch in our remote Repository, where we
114
want to host the project. Let's assume we have a project named
115
"sigil" that we want to put under version control.
95
will want to host the project. Let's assume we have a project named
96
"sigil" that we want to start versioning, and create an empty branch::
119
98
% bzr init sftp://centralhost/srv/bzr/sigil
121
100
This can be thought of as the "HEAD" branch in CVS terms, or as the "trunk"
122
in Subversion terms. We will call this the ``dev`` branch.
101
in Subversion terms. We typically call this the ``dev`` branch.
124
I prefer working in a subdirectory of my home directory to avoid collisions with all
125
the other files that end up there. Also, we will want a project
103
I prefer working in a subdirectory of ``$HOME`` to avoid collisions with all
104
the other stuff that ends up in ``$HOME``. Also, we will want a project
126
105
directory where we can hold all of the different branches we end up
140
117
% bzr commit -m "Initial import of Sigil"
143
In the previous section, we created an empty branch (the ``/sigil``
144
branch) on ``centralhost``, and then checkout out this empty branch
145
onto our workstation to add files from our existing project. There
146
are many ways to set up your working directory, but the steps above
147
make it easy to handle working with feature/bugfix branches. And one
119
There are many ways to setup your working directory, but the above way
120
will makes it easy to handle working with feature/bugfix branches. And one
148
121
of the strong points of Bazaar_ is how well it works with branches.
150
123
At this point, because you have a 'checkout' of the remote branch, any
151
commits you make in ``~/work/sigil/dev/`` will automatically be saved
152
both locally, and on ``centralhost``.
124
commits you make in ``dev/`` will automatically be saved both locally,
125
and on ``centralhost``.
155
128
Developer N: Getting a working copy of the project
156
129
--------------------------------------------------
158
131
Since the first developer did all of the work of creating the project,
159
all other developers would just checkout that branch. **They should
160
still follow** `Setting User Email`_ and `Setting up a local Repository`_.
132
all other developers can just get a checkout of that branch. They should
133
still follow `Setting User Email`_ and `Setting up a local Repository`_.
162
To get a copy of the current development tree::
135
Then to get a copy of the current tip::
164
137
% cd ~/work/sigil
165
138
% bzr checkout sftp://centralhost/srv/bzr/sigil dev
167
140
Now that two people both have a checkout of
168
141
``sftp://centralhost/srv/bzr/sigil``, there will be times when one of
169
the checkouts will be out of date with the current version.
170
At commit time, Bazaar_ will inform the user of this and prevent them from
171
committing. To get up to date, use ``bzr update`` to update the
172
tree with the remote changes. This may require resolving conflicts if the
173
same files have been modified.
142
them is out of date with the current version. Bazaar_ will inform the user
143
of this and prevent them from committing. To get up to date use ``bzr
144
update``, which will update the tree with the remote changes. This may
145
require resolving conflicts, in the case that the same files have been
176
149
Developing on separate branches
177
150
===============================
179
152
So far everyone is working and committing their changes into the same
180
branch. This means that everyone needs to update fairly regularly and
153
branch. Which means that everyone needs to update fairly regularly, and
181
154
deal with other people's changes. Also, if one person commits something
182
that breaks the codebase, then upon syncing, everyone will get the
155
which breaks the codebase, then everyone has to deal with it.
185
Usually, it is better to do development on different branches, and then
157
Usually, it is better to do development on individual branches, and then
186
158
integrate those back into the main branch, once they are stable. This is
187
159
one of the biggest changes from working with CVS/SVN. They both allow you
188
160
to work on separate branches, but their merging algorithms are fairly
189
weak, so it is difficult to keep things synchronized. Bazaar_ tracks
161
weak, so it is difficult to keep things synchronized. Bazaar_ merges track
190
162
what has already been merged, and can even apply changes to files that
191
163
have been renamed.
206
176
% bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes
207
177
% cd doodle-fixes
209
We now have a place to make any fixes we need to ``doodle``. And we would
210
not interrupt people who are working on other parts of the code. Because
211
we have a checkout, any commits made in the ``~/work/sigil/doodle-fixes/``
212
will also show up on ``centralhost``. [#nestedbranches]_ It is also
213
possible to have two developers collaborate on one of these branches, just
214
like they would have collaborated on the ``dev`` branch. [#cbranch]_
216
.. [#nestedbranches] It may look odd to have a branch in a subdirectory of
217
another branch. This is just fine, and you can think of it as a
218
hierarchical namespace where the nested branch is derived from the
179
We now have a place to make any fixes to doodles that we need. And we
180
won't interrupt people who are working on other parts of the code.
181
Because we have a checkout, any commits made in the ``doodle-fixes/`` will
182
also show up on ``centralhost``. [#nestedbranches_]
183
It is also completely possible to have 2 developers collaborate on one of
184
these branches, just like they would have collaborated on the ``dev``
221
187
.. [#cbranch] When using lots of independent branches, having to retype
222
188
the full URL all the time takes a lot of typing. We are looking into
225
191
Which is designed to take a base branch, create a new public branch,
226
192
and create a checkout of that branch, all with much less typing.
227
193
Configuring ``cbranch`` is outside the scope of this document, but the
228
final commands are similar to:
232
% bzr cbranch dev my-feature-branch
234
.. _bzrtools: http://bazaar-vcs.org/BzrTools
194
final commands look like ``bzr cbranch dev my-feature-branch``
196
.. [#nestedbranches] It may look odd to have a branch in a subdirectory of
197
another branch. However, this is just fine, and you can think of it as
198
a heirarchial namespace. Where the nested branch is derived from the
201
.. _bzrtools: https://launchpad.net/products/bzrtools
237
204
Merging changes back
238
205
--------------------
240
When it is decided that some of the changes in ``doodle-fixes`` are ready
241
to be merged into the main branch, simply do::
207
When it is decided that some of the changes in ``doodle-fixes`` is ready
208
to be merged into the main tree, simply do::
243
210
% cd ~/work/sigil/dev
244
211
% bzr merge ../doodle-fixes
246
Now the changes are available in the ``dev`` branch, but they have not
247
been committed yet. This is the time when you want to review the final
248
changes, and double check the code to make sure it compiles cleanly and
249
passes the test suite. The commands ``bzr status`` and ``bzr diff`` are
250
good tools to use here. Also, this is the time to resolve any conflicts.
251
Bazaar_ will prevent you from committing until you have resolved these
252
conflicts. That way you don't accidentally commit the conflict markers.
253
The command ``bzr status`` will show the conflicts along with the other
254
changes, or you can use ``bzr conflicts`` to just list conflicts. Use
255
``bzr resolve file/name`` or ``bzr resolve --all`` once conflicts have
256
been handled. [#resolve]_ If you have a conflict that is particularly
257
difficult to solve you may want to use the ``bzr remerge`` command. It
258
will let you try different merge algorithms, as well as let you see the
259
original source lines (``--show-base``).
213
Now the changes are available in the ``dev`` branch, but they haven't been
214
committed yet. This is the time when you want to review the final changes,
215
and make sure they are what you want. ``bzr status`` and ``bzr diff`` are
216
good tools to use here. Also, there may be some conflicts in files, if
217
there were changes made to the same file. Bazaar_ will prevent you from
218
committing until you have resolved these conflicts. That way you don't
219
accidentally commit the conflict markers. ``bzr status`` will show the
220
conflicts along with the other changes, or you can use ``bzr conflicts``
221
to just list conflicts. Use ``bzr resolve file/name`` or ``bzr resolve
222
--all`` once conflicts have been handled.[#resolve]_
223
If you have a conflict that is particularly difficult to solve you may
224
want to use the ``bzr remerge`` command. It will let you try different
225
merge algorithms, as well as let you see the original source lines
261
228
.. [#resolve] Some systems make you resolve conflicts as part of the merge
262
229
process. We have found that it is usually easier to resolve conflicts
293
259
Shared Repository
294
260
-----------------
296
Bazaar_ has the concept of a "Shared Repository". This is similar to
297
the traditional concept of a repository in other VCSs like CVS and
298
Subversion. For example, in Subversion you have a remote repository,
299
which is where all of the history is stored, and locally you don't
300
have any history information, only a checkout of the working tree
301
files. Note that "Shared" in this context means shared between
302
branches. It *may* be shared between people, but standalone branches
303
can also be shared between people.
305
In Bazaar_ terms, a "Shared Repository" is a location where multiple
306
branches can **share** their revision history information. In order to
307
support decentralized workflows, it is possible for every branch to
308
store its own revision history information. But this is often
309
inefficient, since related branches share history, and they might as
310
well share the storage as well.
262
Bazaar_ has the concept of a `Shared Repository`_. This is similar to the
263
concept of other RCS's repository. Such as in Subversion, where you have a
264
remote repository, which is where all of the history is stored, and
265
locally you don't have any history information, only a checkout of the
266
working tree files. Note that "Shared" in this context means shared
267
between branches. It *may* be shared between people, but standalone
268
branches can also be shared between people.
270
In Bazaar_ terms, a `Shared Repository`_ is a location where multiple
271
branches can **share** their revision history information. Because Bazaar_
272
wants to support decentralized workflows, it is possible for every branch
273
to maintain its own revision history information. But this is often
274
inefficient, since often branches share history, and they might as well
275
share the storage as well.
314
279
vim: tw=74 ft=rst spell spelllang=en_us
added
removed
doc/centralized_workflow.txt
