← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/zen.txt

  • Committer: Ian Clatworthy
  • Date: 2008-05-08 02:43:25 UTC
  • mto: (3480.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 3481.
  • Revision ID: ian.clatworthy@canonical.com-20080508024325-vbz4qjad3zlt2f2q
cleanup, add summary and NEWS item

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/zen.txt
17
17
Understanding revision numbers
18
18
------------------------------
19
19
 
20
 
All revisions in the mainline of a branch will have a simple increasing
 
20
All revisions in the mainline of a branch have a simple increasing
21
21
integer. (First commit gets 1, 10th commit gets 10, etc.) This makes them
22
22
fairly natural to use when you want to say "grab the 10th revision from my
23
23
branch", or "fixed in revision 3050".
128
128
   When viewing the mainline like this, you only see high level commits
129
129
   (instead of a large number of commits uninteresting at this level).
130
130
 
131
 
 * If you have a large project with developers working on sub-teams,
132
 
   you can give each team an integration branch and adopt a policy
133
 
   where only integration branches get merged into the mainline.
134
 
   This cascading hierarchy (project-team-change in this case)
135
 
   will be shown correctly when viewing history.
136
 
 
137
131
 * If required, it makes backing out a feature much easier.
138
132
 
139
133
 * Continuous integration tools can be used to ensure that
142
136
   every single commit as some tests will fail during development.
143
137
   In fact, adding the tests first - TDD style - will guarantee it!)
144
138
 
145
 
In summary, the important point is this:
 
139
In summary, the important points are:
 
140
 
 
141
  *Organize your work using branches.*
146
142
 
147
143
  *Use merge+commit to integrate; use push and pull to mirror.*
148
144
 
 
145
  *Ordered revision numbers and hierarchy make history easier to follow.*
 
146
 
 
147
 
149
148
Each branch has its own view of history
150
149
---------------------------------------
151
150
 
152
151
As explained above, Bazaar makes the distinction between top-level
153
152
revisions (ones you committed in your branch) and merged
154
153
revisions (ones added as ancestors by committing a merge). Each
155
 
branch effectively has its own "view" of history, i.e. different
156
 
branches can give the same revision a different "local revision number".
 
154
branch effectively has its own view of history, i.e. different
 
155
branches can give the same revision a different "local" revision number.
157
156
 
158
157
To extend the example above, here's what the revision history of
159
158
Mary's branch would look like had she decided to merge the project
160
 
mainline into her branch (and commit that merge) after completing it::
 
159
mainline into her branch (and commit that merge) after completing her
 
160
changes::
161
161
 
162
162
  104: Merge mainline
163
163
       100.2.1: Merge feature Y
170
170
  101: Add code and tests for X
171
171
  100: ...
172
172
 
 
173
Once again, it's easy for Mary to look at just *her* top level of history
 
174
to see the steps she has taken to develop this change. In this context,
 
175
merging the mainline (and resolving any conflicts caused by doing that) is
 
176
just one step as far as the history of this branch is concerned.
 
177
 
173
178
It's important to remember that Bazaar is not changing history here, nor
174
179
is it changing the global revision identifiers. You can always use the
175
180
latter if you really want to. In fact, you can use the branch specific
176
181
revision numbers when communicating as long as you provide the branch
177
 
URL as context.
178
 
 
179
 
Revisions are numbered in a stable way, such that if two branches have the
180
 
same revision in their mainline, all revisions in the ancestry of that
181
 
revision will have the same revision numbers. (So if Alice and Bob's
 
182
URL as context. (In many Bazaar projects, developers imply the central
 
183
trunk branch if they exchange a revision number without a branch URL.)
 
184
 
 
185
Merges do not change revision numbers in a branch, though they do
 
186
allocate local revision numbers to newly merged revisions. The only time
 
187
Bazaar will change revision numbers in a branch is when you explicitly
 
188
ask it to mirror another branch.
 
189
 
 
190
Note: Revisions are numbered in a stable way: if two branches have
 
191
the same revision in their mainline, all revisions in the ancestry of that
 
192
revision will have the same revision numbers. For example, if Alice and Bob's
182
193
branches agree on revision 10, they will agree on all revisions before
183
 
that.) Future merges will not change revision numbers. However doing
184
 
``bzr pull`` can change revision numbers, because it changes the
185
 
mainline revisions.
 
194
that.
 
195
 
 
196
Summary
 
197
-------
 
198
 
 
199
Bazaar may *seem* similar to other distributed VCS tools (like Darcs, Git
 
200
and Mercurial) but it has a different internal model that encourages certain
 
201
ways of working. In general, if you follow the advice given earlier - organise
 
202
your work in branches and use merge to collaborate - you'll find Bazaar
 
203
generally does what you expect.
 
204
 
 
205
In coming chapters, we examine various ways of using Bazaar beginning with
 
206
the simplest: using Bazaar for personal projects.
186
207
 
187
208
..
188
209
   vim: ft=rst tw=74 ai