~bzr-pqm/bzr/bzr.dev

1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
1
====================
2
Centralized Workflow
3
====================
4
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
5
.. sectnum::
6
7
8
Overview
9
========
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
10
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 allows them to work in a mix of centralized and decentralized
17
operations.
18
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.
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
25
26
.. _Bazaar: http://bazaar-vcs.org
27
2098.2.4 by John Arbash Meinel
Include a table-of-contents.
28
.. contents::
29
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
30
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
31
Initial Setup
32
=============
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
33
34
These are some reasonably simple steps to setup Bazaar_ so that it works
35
well for you.
36
37
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
38
Setting User Email
39
------------------
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
40
41
Your user identity is stored with each commit. While this doesn't have to
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
42
be accurate or unique, it will be used in log messages and
43
annotations, so it is better to have something real.
44
45
::  
46
47
   % bzr whoami "John Doe <jdoe@organization.com>"
48
49
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
50
Setting up a local Repository
51
-----------------------------
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
52
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
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
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.
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
58
59
The best way to do this is to create a `Shared Repository`_. In general,
60
branches will share their storage if they exist in a subdirectory of a
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
61
`Shared Repository`_.  So let's setup a `Shared Repository`_ in our home
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
62
directory, thus all branches we create underneath will share their history
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
63
storage.
64
65
::
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
66
67
  % bzr init-repo --trees ~
68
69
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
70
Setting up a remote Repository
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
71
---------------------------------
72
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
79
lost.
80
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.
84
85
::
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
86
87
  % bzr init-repo --no-trees sftp://centralhost/srv/bzr/
88
89
You can think of this step as similar to setting up a new cvsroot, or
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
90
subversion repository.
91
92
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
93
Versioning an existing project
94
==============================
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
95
96
Now that we have a repository, let's create a versioned project. Most of
97
the time, you will already have some code that you are working with,
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
98
that you now want to version using Bazaar_. If the code was originally
99
in source control, there are many ways to convert the project to Bazaar_
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
100
without losing any history. However, this is outside the scope of this
101
document. See `Tracking Upstream`_ for some possibilities (section
102
"Converting and keeping history").
103
104
.. _Tracking Upstream: http://bazaar-vcs.org/TrackingUpstream
105
106
.. 
107
   XXX: We really need a different document for discussing conversion of a
108
   project. Right now TrackingUpstream is the best we have, though.
109
110
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
111
Developer 1: Creating the first revision
112
----------------------------------------
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
113
114
So first, we want to create a branch in our remote Repository, where we
115
will want to host the project.  Let's assume we have a project named
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
116
"sigil" that we want to start versioning.
117
118
::
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
119
120
  % bzr init sftp://centralhost/srv/bzr/sigil
121
122
This can be thought of as the "HEAD" branch in CVS terms, or as the "trunk"
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
123
in Subversion terms. We will call this the ``dev`` branch.
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
124
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
125
I prefer working in a subdirectory of my home directory to avoid collisions with all
126
the other files that end up there. Also, we will want a project
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
127
directory where we can hold all of the different branches we end up
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
128
working on.
129
130
::
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
131
132
  % cd ~
133
  % mkdir work
134
  % cd work
135
  % mkdir sigil
136
  % cd sigil
137
  % bzr checkout sftp://centralhost/srv/bzr/sigil dev
138
  % cd dev
139
  % cp -ar ~/sigil/* .
140
  % bzr add
141
  % bzr commit -m "Initial import of Sigil"
142
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
143
144
In the example above, we created an empty branch (the ``/sigil`` branch)
145
on ``centralhost``, and then checkout out this empty branch onto our
146
workstation to add files from our existing project.
147
There are many ways to setup your working directory, but the steps above
148
make it easy to handle working with feature/bugfix branches. And one
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
149
of the strong points of Bazaar_ is how well it works with branches.
150
151
At this point, because you have a 'checkout' of the remote branch, any
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
152
commits you make in ``~/work/sigil/dev/`` will automatically be saved both locally,
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
153
and on ``centralhost``.
154
155
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
156
Developer N: Getting a working copy of the project
157
--------------------------------------------------
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
158
159
Since the first developer did all of the work of creating the project,
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
160
all other developers would just checkout that branch. **They should
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
161
still follow** `Setting User Email`_ and `Setting up a local Repository`_.
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
162
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
163
To get a copy of the current development tree::
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
164
165
  % cd ~/work/sigil
166
  % bzr checkout sftp://centralhost/srv/bzr/sigil dev
167
168
Now that two people both have a checkout of
169
``sftp://centralhost/srv/bzr/sigil``, there will be times when one of
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
170
the checkouts will be out of date with the current version.
171
At commit time, Bazaar_ will inform the user of this and prevent them from
172
committing. To get up to date, use ``bzr update`` to update the
173
tree with the remote changes. This may require resolving conflicts, if the
174
same files have been modified.
175
176
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
177
Developing on separate branches
178
===============================
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
179
180
So far everyone is working and committing their changes into the same
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
181
branch. This means that everyone needs to update fairly regularly and
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
182
deal with other people's changes. Also, if one person commits something
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
183
that breaks the codebase, then upon syncing, everyone will get the
184
problem.
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
185
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
186
Usually, it is better to do development on different branches, and then
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
187
integrate those back into the main branch, once they are stable. This is
188
one of the biggest changes from working with CVS/SVN. They both allow you
189
to work on separate branches, but their merging algorithms are fairly
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
190
weak, so it is difficult to keep things synchronized. Bazaar_ tracks
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
191
what has already been merged, and can even apply changes to files that
192
have been renamed.
193
194
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
195
Creating and working on a new branch
196
------------------------------------
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
197
198
We want to keep our changes available for other people, even if they
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
199
aren't quite complete yet. So we will create a new public branch on
200
``centralhost``, and track it locally.
201
202
::
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
203
204
  % cd ~/work/sigil
205
  % bzr branch sftp://centralhost/srv/bzr/sigil \
206
               sftp://centralhost/srv/bzr/sigil/doodle-fixes
207
  % bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes
208
  % cd doodle-fixes
209
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
210
We now have a place to make any fixes we need to ``doodle``. And we would
211
not interrupt people who are working on other parts of the code.  Because
212
we have a checkout, any commits made in the ``~/work/sigil/doodle-fixes/``
213
will also show up on ``centralhost``. [#nestedbranches]_ It is also
214
possible to have 2 developers collaborate on one of these branches, just
215
like they would have collaborated on the ``dev`` branch. [#cbranch]_
216
217
.. [#nestedbranches] It may look odd to have a branch in a subdirectory of
218
   another branch. This is just fine, and you can think of it as a
219
   heirarchial namespace. Where the nested branch is derived from the
220
   outer branch.
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
221
222
.. [#cbranch] When using lots of independent branches, having to retype
223
   the full URL all the time takes a lot of typing. We are looking into
224
   various methods to help with this, such as branch aliases, etc. For
225
   now, though, the bzrtools_ plugin provides the ``bzr cbranch`` command.
226
   Which is designed to take a base branch, create a new public branch,
227
   and create a checkout of that branch, all with much less typing.
228
   Configuring ``cbranch`` is outside the scope of this document, but the
229
   final commands look like ``bzr cbranch dev my-feature-branch``
230
231
.. _bzrtools: https://launchpad.net/products/bzrtools
232
233
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
234
Merging changes back
235
--------------------
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
236
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
237
When it is decided that some of the changes in ``doodle-fixes`` are ready
238
to be merged into the main branch, simply do::
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
239
240
  % cd ~/work/sigil/dev
241
  % bzr merge ../doodle-fixes
242
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
243
Now the changes are available in the ``dev`` branch, but they have not
244
been committed yet. This is the time when you want to review the final
245
changes, and double check the code to make sure it compiles cleanly and
246
passes the test suite. The commands ``bzr status`` and ``bzr diff`` are
247
good tools to use here. Also, this is the time to resolve any conflicts.
248
Bazaar_ will prevent you from committing until you have resolved these
249
conflicts. That way you don't accidentally commit the conflict markers.
250
The command ``bzr status`` will show the conflicts along with the other
251
changes, or you can use ``bzr conflicts`` to just list conflicts. Use
252
``bzr resolve file/name`` or ``bzr resolve --all`` once conflicts have
253
been handled. [#resolve]_ If you have a conflict that is particularly
254
difficult to solve you may want to use the ``bzr remerge`` command. It
255
will let you try different merge algorithms, as well as let you see the
256
original source lines (``--show-base``).
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
257
258
.. [#resolve] Some systems make you resolve conflicts as part of the merge
259
   process. We have found that it is usually easier to resolve conflicts
260
   when you have the view of the entire tree, rather than just a single
261
   file. It gives you much more context, and also lets you run tests as
262
   you resolve the problems.
263
264
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
265
Recommended Branching
266
---------------------
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
267
268
One very common way to handle all of these branches is to give each
269
developer their own branch, and their own place to work in the central
270
location. This can be done with::
271
272
  % bzr branch sftp://centralhost/srv/bzr/sigil \
273
               sftp://centralhost/srv/bzr/sigil/user-a
274
  % bzr branch sftp://centralhost/srv/bzr/sigil \
275
               sftp://centralhost/srv/bzr/sigil/user-b
276
277
This gives each developer their own branch to work on. And, they can
278
easily create a new feature branch for themselves with just[#cbranch]_::
279
280
  % bzr branch sftp://centralhost/srv/bzr/sigil/user-a \
281
               sftp://centralhost/srv/bzr/sigil/user-a/feature 
282
  % cd ~/work/sigil
283
  % bzr checkout sftp://centralhost/srv/bzr/sigil/user-a/feature myfeature
284
285
2098.2.3 by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections.
286
Glossary
287
========
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
288
289
Shared Repository
290
-----------------
291
2098.2.2 by John Arbash Meinel
minor cleanup
292
Bazaar_ has the concept of a "Shared Repository". This is similar to the
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
293
concept of other RCS's repository. Such as in Subversion, where you have a
294
remote repository, which is where all of the history is stored, and
295
locally you don't have any history information, only a checkout of the
296
working tree files. Note that "Shared" in this context means shared
297
between branches. It *may* be shared between people, but standalone
298
branches can also be shared between people.
299
2098.2.2 by John Arbash Meinel
minor cleanup
300
In Bazaar_ terms, a "Shared Repository" is a location where multiple
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
301
branches can **share** their revision history information. Because Bazaar_
302
wants to support decentralized workflows, it is possible for every branch
303
to maintain its own revision history information. But this is often
2098.2.1 by John Arbash Meinel
Apply changes recommended by Alaa Salman
304
inefficient, since related branches share history, and they might as well
1964.2.1 by John Arbash Meinel
Adding basic documentation about working with a central repository
305
share the storage as well.
306
307
308
.. 
309
   vim: tw=74 ft=rst spell spelllang=en_us