7
Martin Pool <mbp@sourcefrog.net>
9
:Date: December 2004, Noosa.
18
*Bazaar-NG should be a joy to use.*
20
What if we started from scratch and tried to take the best features
21
from darcs, svn, arch, quilt, and bk?
23
Don't get the sum of all features; rather get the minimum features
24
that make it a joy to use. Choose simplicity, in both interface and model.
25
Do not multiply entities
28
*Make it work; make it correct; make it fast* -- Ritchie(?)
35
* Unify archives and branches; one archive holds one branch. If you
36
want to publish multiple branches, just put up multiple directories.
38
* Explicitly add/remove files only; no names or tagline tagging. If
39
someone wants to do heuristic detection of renames that's fine, but
40
it's not in the core model.
42
Quilt indicates an interesting approach: patches themselves are the
43
thing we're trying to build. We don't just want a record of what
44
happened, but we want to build up a good description of the change
45
that will be implied when it's integrated. This implies that we want
46
to be able to change history quite a lot before merging upstream; or
47
at least change our description of what will go up.
53
* Unix design philosophy (via Peter Miller), tempered by modern
56
- least unnecessary output
58
- little dependence on *specific* external tools
62
- least overlap with cooperating tools
66
__ http://www.jwz.org/doc/worse-is-better.html
68
- *Simplicity: the design must be simple, both in implementation and
69
interface. It is more important for the implementation to be
70
simple than the interface. Simplicity is the most important
71
consideration in a design.*
73
- *Correctness: the design must be correct in all observable
74
aspects. It is slightly better to be simple than correct.*
77
- *Consistency: the design must not be overly inconsistent. Consistency
78
can be sacrificed for simplicity in some cases, but it is better to
79
drop those parts of the design that deal with less common
80
circumstances than to introduce either implementational complexity
83
- *Completeness: the design must cover as many important situations as
84
is practical. All reasonably expected cases should be
85
covered. Completeness can be sacrificed in favor of any other
86
quality. In fact, completeness must sacrificed whenever implementation
87
simplicity is jeopardized. Consistency can be sacrificed to achieve
88
completeness if simplicity is retained; especially worthless is
89
consistency of interface.*
91
* Try to get a reasonably tasteful balance between having something
92
that works out of the box but also has composable parts. Provide
93
mechanism rather than policy but not to excess.
95
* Files have ids to let us detect renames without having to walk the
98
If there are conflicts in ids they can in principle be resolved.
99
There might be a ``merge --by-name`` to allow you to force two trees
100
into agreement on IDs. If the merge sees two files with the same
101
name and text then it should conclude that the files merged.
103
It would be nice if there were some way to make repeated imports of
104
the same tree give the same ids, but I don't think there is a safe
105
feasible way. Sometimes files start out the same but really should
106
diverge; boilerplate files are one example.
108
* Archives are just directories; if you can read/write the files in
109
them you can do what you need. This works even over http/sftp/etc.
110
Or at least this should work for read-only access; perhaps for
111
writing it is reasonable to require a svn+ssh style server invoked
114
Of course people should not edit the files in there by hand but in
115
an emergency it should be possible.
117
* Storing archives in plain directories means making some special
118
effort to make sure they can be rolled back if the commit is
119
interrupted any time. On truly malicious filesystems (NFS) this may
120
be quite difficult, but at a minimum it should be possible to roll
121
back whatever was uncommitted and get to a reasonable state. It
122
should also be reasonably possible to mirror branches using rsync,
123
which may transfer files in arbitrary order and cannot handle files
124
changing while in flight.
126
Recovering from an interrupted commit may require a special ``bzr
127
fix`` command, which should write the results to a new branch to
128
avoid losing anything.
130
* Branches carry enough information to recreate any previous state of
131
the branch (including its ancestors).
133
This does not necessarily mean holding the complete text of all
134
those patches, but we do store at least a globally unique identifier
135
so that we can retrieve them.
137
* Commands should correspond to svn or cvs as much as possible: add,
138
get, copy, commit, diff, status, log, merge.
140
* We have all the power of mirroring, but without needing to introduce
141
special concepts or commands. If you want somebody's branch
142
available offline just copy it and keep updating to pull in their
143
changes; if you never make any changes the updates will always
146
* It is useful to be able to easily undo a previous change by
147
committing the opposite. I had previously imagined requiring all
148
patches to be stored in a reversible form but it's enough to just do
149
backwards three-way merges.
151
* Patches have globally unique IDs which uniquely identify them.
153
* As a general principle we separate identification (which must be
154
globally unique) from naming (which must be meaningful to users).
155
Arch fuses them, which makes the human names long and prevents them
156
ever being reused. Monotone doesn't have human-friendly names.
158
* Users are identified by something like an email address;
159
``user@domain``. This need not actually be a working email
160
address; the point is just to piggyback on domain names to get
161
human-readable globally unique names.
163
* Everything will be designed from the beginning to be safe and
164
reasonable on Windows and Unix.
166
* History is append-only. Patches are recorded along with the time at
167
which they were committed; if time steps backwards then we give a
168
warning (but probably commit anyhow.) This means we can reliably
169
reproduce the state of the branch at any previous point, just by
170
backing out patches until we get back there.
172
This is also true at a physical level as much as possible; once a
173
patch is committed we do not overwrite it. This should make it less
174
likely that a failure will corrupt past history. However, we may
175
need some indexes which are updated rather than replaced; they
176
should probably be atomically updated.
178
* Storage should be reasonably transparent, as much as possible. (ie
179
don't use SQLite or BDB.) At the same time it should be reasonably
180
efficient on a wide range of systems (ie don't require reiserfs to
183
Programmers who look behind the covers should feel comfortable that
184
their data is safe, and hopefully pleased that the design is
187
* Unrecognized files cause a warning when you try to commit, but you
188
can still commit. (Same behavior as CVS/Subversion; less discipline
191
If you wish, you can change this to fail rather than just warn; this
192
can be done as tree policy or as an option (eg ``commit --strict``)
194
* Files may be ignored by a glob; this can be applied globally (across
195
the whole tree) or for a particular directory. As a special
196
convenience there is ``bzr ignore``.
198
* If branches move location (e.g. to a new host or a different
199
directory), then everyone who uses them needs to know the new URL by
200
some out-of-band method.
202
* All operations on a branch or pair of branches can be done entirely
203
with the information stored in those branches. Bazaar-NG never needs to
204
go and look at another branch, so we don't need unique branch names
205
or to remember the location of branches.
207
* Store SHA-1 hashes of all patches, also store hashes of the tree
208
state in each revision. (We need some defined way to make a hash of
209
a tree of files; for a start we can just cat them together in order
212
Hashes are stored in such a way that we can switch hash algorithms
213
later if needed if SHA-1 is insecure.
215
* You can also sign the hashes of patches or trees.
217
* All branches carry all the patches leading up to their current
218
state, so you can recreate any previous state of that branch,
219
including the branches leading up to it.
221
* A branch has an append-only history of patches committed on this
222
branch, and also an append-only history of patches that have been
225
* A commit log message file is present in .bzr-log all the time; you
226
can add notes to it as you go along. Some commands automatically
227
add information to this file, such as when merging or reversing
230
The first line of the message is used as the summary.
232
* Commands that make changes to the working copy will by default baulk
233
if you have any uncommitted changes. Such commands include ``merge``
234
and ``reverse``. This is done for two reasons: to avoid losing your
235
changes in the case where the merge causes problems, and to try to
236
keep merges relatively pure. You can force it if you wish.
238
(*pull* is possibly a special case; perhaps it should set aside
239
local changes, update, and then reapply them/remerge them?)
241
* Within a branch, you can refer to commits by their sequence number;
242
it's nice and friendly for the common case of looking at your
245
* You can generate a changelog any time by looking at only local
246
files. Automatically including a changelog in every commit is
247
redundant and so can be eliminated. Of course if you want to
248
manually maintain a changelog you can do that too.
250
* At the very least we should have ``undo`` as a reversible
251
``revert``. It might be even better to have a totally general undo
252
which will undo any operation; this is possible by keeping a journal
255
* Perhaps eventually move to storing changesets in single text files,
256
containing file diffs and also information on renames, etc. The
257
format should be similar to that of ``tla show-changeset``, but
260
* Pristines are kept in the control directory; pristines are
261
relatively expensive to recreate so we might want to keep more than
264
(Robert says that keeping pristines under there can cause trouble
265
with people running recursive commands across the source tree, so
266
there should probably be some other way to do it. If pristines are
267
identified by their hash then we can have a revlib without needing
268
unique branch names.)
270
* Can probably still have cacherevs for revisions; ideally
271
autogenerated in some sensible way. We know the tree checksum for
272
each revision and can make sure we cached the right thing.
274
* Bazaar-NG should ideally combine the best merging features of
275
Bitkeeper and Arch: both cherry-picking and arbitrary merging within
276
a graph. The metaphor of a bazaar or souk is appropriate: many
277
independent agents, exchanging selected patches at will.
279
* Code should be structured as a library plus a command-line client;
280
the library could be called from any other client. Therefore
281
communication with the user should go through a layer, the library
282
should not arbitrarily exit() or abort(), etc.
284
* Any of these details are open to change. If you disagree, write and
285
say so, sooner rather than later. There will be a day in the future
286
where we commit to compatibility, but that is a while off.
288
* Timestamps obviously need to be in UTC to be meaningful on the
289
network. I guess they should be displayed in localtime by default
290
and you can change that by setting $TZ or perhaps some option like
291
``--utc``. It might be cool to also capture the local time as an
292
indicator of what the committer was doing.
294
* Should probably have some kind of progress indicator like --showdots
295
that is easy to ignore when run from a program (especially an
296
editor); that probably means avoiding tricks with carriage return.
297
(That might be a problem on Windows too.)
299
* What date should be present on restored files? We don't remember
300
the date of individual files, but we could set the date for the
303
* One important layer is concerned with reproducing a previous
304
revision from a given branch; either the whole thing or just a
305
particular file or subdirectory. This is used in many different
306
places. We can potentially plug in different storage mechanisms
307
that can do this; either a very transparent and simple file-based
308
store as in darcs and arch, or perhaps a more tricky/fast
309
database-based system.
312
Entities and terminology
313
------------------------
315
The name of the project is *Bazaar-NG*; the top-level command is
321
Development in Bazaar-NG takes places on branches. A branch records
322
the progress of a *tree* through various *revisions* by the
323
accumulation of a series of *patches*.
325
We can point to a branch by specifying its *location*. At first this
326
will be just a local directory name but it might grow to allow remote
327
URLs with various schemes.
329
Branches have a *name* which is for human convenience only; changesets
330
are permanently labelled with the name of the branch on which they
331
originated. Branch names complement change descriptions by providing
332
a broader context for the purpose of the change. Typically the branch
333
name will be the same as the last component of the directory or path.
335
There is no higher-level grouping than branches. (Nothing that
336
corresponds to repositories in CVS or Subversion, or
337
archives/categories/versions in Arch.) Of course it may be a good
338
practice to keep your branches organized into directories for each
339
project, just as you might do with tarballs or cvs working
342
Bazaar-NG makes forking branches very easy and common.
349
The tree in a branch at a particular moment, after applying all the
350
patches up to that point.
356
A UUID for a versioned file, assigned by ``bzr add``.
362
A smart diff, containing:
364
* unidiff hunks for textual changes
366
* for each affected file, the file id and the name of that file before
367
and after the delta (they will be the same if the file was not renamed)
369
* in future, possibly other information describing symlinks,
372
A delta can be generated by comparing two trees without needing any
375
Although deltas have some diff context that would allow fuzzy
376
application they are (almost?) always exactly applied to the correct
383
(also known as a patch)
385
A changeset represents a commit to a particular branch; it
386
incorporates a *delta* plus some header information such as the name
387
of the committer, the date of the commit, and the commit message.
393
A tree of files and directories. A branch minus the Bazaar-NG control files.
404
Branches are identified by their directory name or URL::
406
bzr branch http://kernel.org/bzr/linux/linux-2.6
407
bzr branch ./linux-2.6 ./linux-2.6-mbp-partitions
409
Branches have human-specified names used for tracing patches to their
410
origin. By default this is the last component of the directory name.
416
Revisions within a branch may be identified by their sequence number
417
on that branch, or by a tag name::
419
bzr branch ./linux-2.6@43 ./linux-2.6-old
420
bzr branch ./linux-2.6@rel6.8.1 ./linux-2.6.8.1
422
You may also use the UUID of the patch or by the hash of that
423
revision, though sane humans should never (need to) use these::
425
bzr log ./linux-2.6@uuid:6eaa1c41-34b8-4e0e-8819-acb5dfcabb78
426
bzr log ./linux-2.6@hash:4bf00930372cce9716411b266d2e03494f7fe7aa
428
Revision ranges are given as two revisions separated by a colon (same
431
bzr merge ../distcc-doc@4:10
437
Authors are identified by their email address, taken from ``$EMAIL``
446
When a revision is committed, Bazaar-NG records an "inventory" which
447
essentially says which version of each file should be assembled into
448
which location in the tree. It also includes the SHA-1 hash and the
456
Merges are carried out in Bazaar-NG by a three-way merge of trees. Users
457
can choose to merge all changes from another branch, or a particular
458
subset of changes. In either case Bazaar-NG chooses an appropriate
459
common base appropriately, although there should perhaps also be an
460
option to specify a different base.
462
I have not solved all the merge problems here. I do think that this
463
design preserves as much information as possible about the history of
464
the code and so gives a good foundation for smart merging.
465
The basic merge operation is a 3-way diff: we have three files *BASE*,
466
*OTHER* and *MINE* and want to produce a result. There are many
467
different tools that could be used to resolve this interactively or
470
There are some cases where the best base is not a state that ever
471
occurred on the two branches. One such case is when there are two
472
branches that have both tracked an upstream branch but have never
473
previously synced with each other. In this case we suggest that
474
people manually specify the base::
476
bzr merge --base linus-2.6 my-2.6
478
Merges most commonly happen on files, but can also occur on metadata.
479
For example we may need to resolve a conflict between file ids to
480
decide what name a file should have, or conversely which id it should
483
When merging an entire branch, the base is chosen as the last revision
484
in which the trees manifests were identical.
486
If merging only selected revisions from a branch (ie cherry picking)
487
then the base is set just before the revisions to be merged.
489
A three-way merge operates on three inputs: THIS, OTHER, and a BASE.
490
Any regions which have been changed in only one of THIS and OTHER, or
491
changed the same way in both will be carried across automatically.
492
Regions which differ in all three trees are conflicts and must be
495
The merge does not depend upon any states the trees may have
496
passed through in between the revisions that are merged.
498
After the merge, the destination tree incorporates all the patches
499
from the branch region that was merged in.
503
Sending patches by email
504
------------------------
506
Patches can be sent to someone else by email, just by posting the
507
string representation of the changeset. Could also post the GPG
510
The changeset cannot itself contain its uniquely-identifying hash.
511
Therefore I suppose it needs some kind of super-header which says what
512
the patch id is; this can be verified by comparing it to the hash of
513
the actual changeset. This in turn applies that the text must be
514
exactly preserved in email, so possibly we need some kind of
515
quoted-printable or ascii-armoured form.
517
Another approach would be to not use the hash as the id, but rather
518
something else which allows us to check the patch is actually what it
519
claims to be. For example giving a GPG key id and a UUID would do
520
just as well, and *would* allow the id to be included within the
521
patch, as would giving an arch-style revision ID, assuming we can
522
either map the userid to a GPG key and/or check against a trusted
525
There are two ways to apply such a received patch. Ideally it tells
526
us a revision of our branch from which it was based, probably by
527
specifying the content hash. We can use that as the base, make a
528
branch there, apply the patch perfectly, and then merge that branch
529
back in through a 3-way merge. This gives a clean reconciliation of
530
changes in the patch against any local changes in the branch since the
533
If we do not have the base for the patch we can try apply it using
534
a similar mechanism to regular patch, which might cause conflicts. Or
535
maybe it is not worth special-casing this; we could just require
536
people to have the right basis to accept a patch.
543
History is generally append-only; once something is committed it
544
cannot be undone. We need this to make several important guarantees
545
about being able to reconstruct previous versions, about patches being
546
consistent, and so on and on.
548
However, pragmatically, there are a few cases where people will insist
549
on being able to fudge it. We need to accommodate those as best we
550
can, within the limits of causality. In other words, what is
551
physically and logically possible should not be arbitrarily forbidden
552
by the software (though it might be enormously discouraged).
554
The basic transaction is a changeset/patch/commit. There is little
555
value and hellish complexity in introducing meta-changesets or trying
556
to update already-committed changes.
562
*Oops, I pressed Save too soon, and the commit message is wrong.* This
563
happens all the time.
565
If no other branch has taken that change, there is no harm in fixing
566
the message. Noticing the problem right away is probably a very
569
Therefore, you can change the descriptive text (but not any other
570
metadata) of a changeset in your tree. This will not propagate to
571
anyone else who has already accepted the change. Nothing will break,
572
but they'll still see the original (incorrect/incomplete) commit.
575
Committed confidential information
576
''''''''''''''''''''''''''''''''''
578
If you just added a file you didn't mean to add then you can simply
579
commit a second changeset to remove it again. However, sometimes
580
people will accidentally commit sensitive/confidential information,
581
and they need to remove it from the history.
583
If anyone else has already taken the changeset we can't prevent them
584
seeing or keeping the information. You need to find them and ask them
585
nicely to remove it as well. Similarly, if you've mirrored your
586
branch elsewhere you need to fix it up by hand. This additional
587
manual work is a feature because it gives you some protection against
588
accidentally destroying the wrong thing.
590
A similar but related case is accidentally committing an enormous
591
file; you don't want it to hang around in the archive for ever. (In
592
fact, it would need to be stored twice, once for the original commit
593
and again for a reversible remove changeset.)
595
Here is our suggestion for how to fix this: make a second branch from
596
just before the undesired commit, typically by specifying a timestamp.
597
If there are any later commits that need to be preserved, they can be
598
merged in too. Possibly that will cause conflicts if they depended on
599
the removed changeset, and those changes then need to be resolved.
609
(I don't think we should implement this soon, if at all, but people
610
might want to know it's possible.)
612
Bazaar-NG relies on each branch being able to recreate any of its
613
predecessor states. This is needed to do really intelligent merging.
615
However, you might eventually get sick of keeping all the history
616
around forever. Therefore, we can set a history horizon, ignoring all
617
patches before that point.
619
The patches are still recorded as being merged but we do not keep the
620
text of the patches. Perhaps we add them to a special list.
622
Merges with a tree that have no history in common since the horizon
623
will be somewhat harder.
629
**See also work-log.txt for what I'm currently doing.**
631
* Start by still using Arch changeset format, do-changeset and delta
632
commands, possibly also for merge.
634
* Don't do any merges automatically at first but rather just build
635
some trees and let the user run dirdiff or something.
637
* Don't handle renames at first.
639
* Don't worry about actually being distributed yet; just work between
640
local directories. There are no conceptual problems with accessing
647
* History cannot be rewritten, aside from a couple of special
650
* Allows cherry-picking, which is not possible on bk or most others.
652
* Allows merges within an arbitrary graph (rather than a line, star or
653
tree), which can be done by bk but not by arch or others.
655
* History-sensitive merges allow safe repeated merges and mutual
656
merges between parallel lines.
658
* Patches are labelled with the history of branches they traversed to
659
their current location, which is previously unique to Arch.
661
* Would aim to be almost as small and simple as Quilt.
663
* Does not need archives to be registered.
665
* Like darcs and bk, remembers the last archive you pulled from and
666
uses this as the default. Also as a bonus remembers all branches
667
you previously pulled and their name, so that it is as if they were
670
* Because patches do not change when they move around (as in Darcs),
671
they can be cryptographically signed.
673
* Recognizes that textually non-conflicting merges may not be a
674
correct merge and may not work, and so should not be auto-committed.
675
The developer must have a chance to intervene after the merge and
676
before a commit. (I think Monotone is wrong on this.)
684
We recommend that people using Bazaar-NG follow these practices and
687
* Develop independent features in separate branches. It's easier to
688
keep them separate and merge later than to mix things together and
689
then try to separate them. Although cherry picking is possible,
690
it's generally harder than keeping the code separate in the first
693
* Although you can merge in a graph, it can be easier to understand
694
things if you keep them roughly sorted into a star of downstream and
697
* Merge off your laptop/workstation into a personal stable tree at
698
regular changes; this protects against accidentally losing your
699
development branch for any reason.
701
* Try to have relatively "pure" merges: a single changeset that merges
702
changes should make only those merges and any edits needed to fix
705
* You can use reStructuredText (like this document) for commit
706
messages to allow nicer formatting and automatic detection of URLs,
707
email addreses, lists, etc. Nothing requires this.
717
A patch (i.e. commit to a branch) exists at three levels:
719
* the hash of the patch, which is used as its globally-unique name
721
* the headers of the patch, including:
723
- the human-readable name of the branch to which the changeset was committed
725
- free-form comments about the changeset
727
- the email address and name of the user who committed the changeset
729
- the date when the changeset was committed to the branch
731
- the UUIDs of any patches merged by this change
733
- the hash of the before and after trees
735
- the IDs of any files affected by the change, and their names
736
before and after the change, and their hash before and after the
739
* the actual text of the patch, which may include
743
- xdeltas (in reversible pairs?)
745
- complete files for adds/deletes, or for binaries
747
At the simplest level a branch knows just the IDs of all of the
748
patches committed to it. More usually it will also have all their
749
logs or all their text.
751
Using the IDs, it can retrieve the patches when necessary from a
752
shared or external store. By this means we can have many checkouts,
753
each of which looks like it holds all of its history, without actually
754
using a lot of space. When pulling down a remote branch by default
755
everything will be mirrored, but there might be an option to only get
756
the inventory or only the logs.
758
Keeping the relatively small header separate from the text makes it
759
easy to get only the header information from a remote machine. One
760
might also when offline like to see only the logs but not necessarily
763
Only the basic policy (keep everything everywhere) needs to be done in
764
the first release of course.
766
The headers need to be stored in some format that allows moderately
767
structured data. Ideally it would be both human readable and
768
accessible from various languages. In the prototype I think I'll use
769
Python data format, but that's probably not good in the long term. It
770
may be better to use XML (tasteless though that is) or perhaps YAML or
771
RFC-2822 style. Python data is probably not secure in the face of
774
The date should probably be shown in ISO form (unoptimal though that
781
Unresolved questions and other ideas
782
------------------------------------
785
Pulling in inexact matches
786
''''''''''''''''''''''''''
788
If ``update`` pulls in patches noninteractively onto the history, then
789
there are some issues with patches that do not exactly match. Some
792
* You may pull in a patch which causes your tree to semantically
793
break. This might be avoided by having a test case which is checked
796
* The patch may fuzzily apply; this is OK.
798
If we pull in a patch from elsewhere then we will have a signature on
799
the patch but not a signature for the whole cacherev.
804
Have pristines/working directory by default?
805
''''''''''''''''''''''''''''''''''''''''''''
807
It seems a bit redundant to have two copies of the current version of
808
each file in every repository, even ones in which you'll never edit.
809
Some fixes are possible:
811
* don't create working copy files
813
* hard link working copies into pristine directory (can detect
814
corruption by having SHA-1 sums for all pristine files)
816
I think it's reasonable to have
823
We have a single metadata directory at the top-level of the tree: ``.bzr``.
824
There is no value in having it non-hidden, because it can't be seen
825
from subdirectories anyhow. Apparently three-letter names after a dot
826
are fine on Windows -- it works for ``.svn``.
832
Unicode, line endings, etc. Ignore this for now?
834
Case-insensitive file names? Maybe follow Darcs in forbidding files
835
that differ only in case.
838
Always use 3-way merge
839
''''''''''''''''''''''
841
I think using .rej files and fuzzy patches is confusing/unhelpful.
843
I would like to use 3-way merges between appropriate coordinates as
844
the fundamental mechanism for all 'merge'-type operations.
846
Is there any case where .rej files are more useful? Why would you
847
ever want that? Some people seem to `prefer them`__ in Arch.
849
__ http://wiki.gnuarch.org/moin.cgi/Process_20_2a_2erej_20files
851
I guess when cherry-picking you might not be able to find an
852
appropriate ancestor for diff3? I think you can; anyhow wiggle can
853
transform rejects into diff3-style conflicts so why not do that?
855
Miles says there that he prefers .rej files to conflict markers
856
because they give better results for complex conflicts.
858
Perhaps we should just always produce both and let people use whatever
861
Another suggestion is the *rej_* tool, which helps fix up simple
864
There are four basic rejects fixable via rej.
866
1) missing context at the top or bottom of the hunk
867
2) different context in the middle of the hunk
868
3) slightly different lines removed by the hunk than exist in the file
869
4) Large hunks that might apply if they were broken up into smaller ones.
871
.. _rej: ftp://ftp.suse.com/pub/people/mason/rej/
877
One reason people say they like archives is that all new work in that
878
archive will be automatically mirrored off your laptop, if it's
879
already set up to mirror that archive.
883
Control files out of tree
884
'''''''''''''''''''''''''
886
Some people would like to have absolutely no control files in their
887
tree. This is conceptually easy as long as we can find both the
888
control files and working directory when a command is run.
890
As a first step, the ``.bzr`` directory can be replaced by a symlink,
891
which will prevent recursive commands looking into it. Another
892
approach is to put all actual source in a subdirectory of the tree, so
893
that you never need to see the directory unless you look above the
896
If this is not enough, we might ask them to have an environment
897
variable point to the control files, or have a map somewhere
898
associating working directories with their control files.
899
Unfortunately both of those seem likely to come loose and whip around
903
Representation of changesets
904
''''''''''''''''''''''''''''
906
Using patches is nice for plain text files. In general we want the
907
old and new names to correspond, but these are only for decoration;
908
the file id determines where the patch really goes.
910
* Should they be reversible?
912
* How to represent binary diffs?
914
* How to represent adds/removes?
916
* How to zip up multiple changes into a single bundle?
918
Reversibility is very important. We do not need it for regular
919
merges, since we can always recover the previous state. We do need it
920
for application of isolated patches, since we may not be able to
921
recover the prior state. It might also help when building a previous
924
Of course we can have an option to show deletes or to make the diff
925
reversible even if it normally is not.
927
It is very nice that plain diffs can be concatenated into a single
928
text file. This is not easily possible with binary files, xdeltas,
929
etc. Of course it is uncommon to display binary deltas directly or
930
mail them, but if mailing is really required we could use base64 or
933
Perhaps it would be reasonable to just store xdeltas between versions.
935
Perhaps each changeset body should be a tar or zip holding the
936
patches, though in simpler form than Arch.
938
(Since these are free choices, perhaps stick closely to what Arch
945
Do we need the generalized continuations currently present in Arch, or
946
will a more restricted type do?
948
One use case for arch continuation tags is to make a release branch
949
which contains only tags from the development branch.
951
Maybe want darcs-style tags which just label the tree at various
952
points; more familiar to users perhaps?
956
bzr fork http://samba.org/bzr/samba/main ./my-samba
958
1. creates directory my-samba
959
2. copies contents of samba main branch
960
3. the parent becomes samba-main
961
4. parent is the default place you'll pull from & push to
963
Is there a difference between "contains stuff from samba-main" and "is
964
branched from samba-main"?
971
Is there any sense in having a command to copy a file, or to rejoin
972
several files with different IDs?
974
Joining might be useful when the same tree is imported several times,
975
or the same new-file operation is done in different trees.
982
Local clocks can be wrong when they record a commit. This means that
983
changes may be irrevocably recorded with the wrong time, and that in
984
turn means that later changes may seem to come from before earlier
985
changes. We can give a warning at the later time, but short of
986
refusing the commit there is not much we can do about it.
989
Annotate/blame/praise
990
---------------------
992
``cvs annotate`` is pretty useful for understanding the history of
993
development. At the same time it is not quite trivial to implement,
994
so I plan to make sure all the necessary data is easily accessible and
995
then defer actually writing it. Possibly the most complicated part is
996
something to read in a diff and find which lines came from where.
998
What we need is a way to easily follow back through the history of a
999
file, this is easily done by walking back along the branch. Since we
1000
have revision numbers within a branch we have a short label which can
1001
be put against each line; we can also put a key at the bottom with
1002
some fields from each revision showing the committer and comment.
1004
For the case of merge commits people might be interested to know which
1005
merged patch brought in a change. We cannot do this completely
1006
accurately since we don't know what the person did during the manual
1007
resolution of the merge, but by looking for identical lines we can
1008
probably get very close. We can at the very least tell people the
1009
hash of all patches that were merged in so they can go and have a look
1017
I think nothing here requires loading the whole tree into memory, as
1018
Darcs does. We can detect renames and then diff files one by one.
1020
Because patches cannot change or be removed once they are committed or
1021
merged, we do not need to diff the patch-log, which is a problem in
1024
We do need to hold the whole list of patches in memory at various
1025
points but that should be at most perhaps 100,000 commits.
1027
We do need to pull down all patches since forever but that's not too
1030
Most heavy lifting can be done by GNU diff, patch and diff3, which are
1033
Patches should be reasonably proportionate to the actual size of
1034
changes, not to the total size of the tree -- we should only list the
1035
hash and id for files that were touched by the change. This implies
1036
that generating the manifest for any given revision means walking from
1037
the start of history to that revision. Of course we can cache that
1038
manifest without necessarily caching the whole revision.
1040
* The dominant effect on performance in many cases will be network
1041
round-trips; as Tom says "every one is like punching your user in
1044
The network protocol can/should try to avoid them.
1046
However, here's an even lazier idea: by making it possible to use
1047
rsync for moving trees around, we get an insanely pipelined protocol
1050
It's not always suitable (as when committing to a central tree), but
1051
it will often work. Cool!
1053
Safely using rsync probably requires user intervention to make sure
1054
that the tree is idle at the time the command runs; otherwise the
1055
ordering of files arriving makes it really hard to know that we have
1056
a consistent state. I guess we can just ignore patches that are
1063
It might be nice to present hashes in BubbleBabble or some similar
1064
form to make it a bit easier on humans who have to see them. This can
1065
of course be translated to and from binary. On the other hand there
1066
is something in favour of regular strings that can be easily verified
1069
We can have a Henson Mode in which it never trusts that files with the
1070
same hash are identical but always checks it. Of course if SHA-1 is
1071
broken then GPG will probably be broken too...
1078
> xizif-segim-vipyz-dyzak-gatas-sifet-dynir-gegon-borad-cetit-tixux
1081
> qvTGHdzF6KLavt4PO0gs2a6pQ00=
1084
> aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
1087
Hex is probably the most reasonable tradeoff.
1093
I don't want to get into general versioning of file metadata like
1094
permissions, at least in the first version; it's hard to say what
1095
should be propagated and what should not be. This is a source code
1098
It may be useful to carry some very restricted bits, like *read only*
1099
or *executable*; I think these are harmless.
1101
The only case where people generally want to remember permissions and
1102
ownership is when versioning ``/etc``, which is quite a special case.
1103
Perhaps this should be deferred to a special script such as the
1104
``cvs-conf`` package.
1110
There are many cases where we need to compare trees; perhaps the most
1111
common is just diffing the tree to see what changed. For small to
1112
medium trees it is OK to just diff everything in the tree, and we can
1113
do just this in the first version. This runs into trouble for
1114
kernel-sized trees, where reading every
1120
There is some fear that distributed version control (many branches)
1121
will encourage projects to fork. I don't think this is necessarily
1124
A fundamental principle of Bazaar is that is not the tool's place to
1125
make you run a project a particular way. The tool enables you to do
1126
what you want. The documentation and community might suggest some
1127
practices that have been useful for other projects, but the choice is
1128
up to you. There are principles for running open source projects that
1129
are useful regardless of tool, and Bazaar supports them. They include
1130
encouraging new contributors, building community, managing a good
1131
release schedule and so on, but I won't enumerate them all here (and I
1132
don't claim to know them all.)
1134
Bazaar reduces some pressures that can lead to forking. There need
1135
not be fights about who gets commit access: everyone can have a branch
1136
and they can contribute their changes. Radical new development can
1137
occur on one branch while stabilization occurs on another and a new
1138
feature or port on a third. Both creating the branches and merging
1139
between them should be easier in the Bazaar than with existing
1140
systems. (Though of course there may be technical difficulties that
1141
no tool can totally remove.)
1143
Sometimes there really is a time for a fork, for various reasons:
1144
irreconcilable differences on technical direction or personality. If
1145
that happens, Bazaar makes the break less total: the projects can
1146
still merge patches, share bug fixes and features, and even eventually
1153
A key goal is simplicity and user-friendliness; this is easier to
1154
build into a new tool than to fix in an existing tool. Nevertheless
1155
we want to provide a smooth upgrade path from Arch, CVS, and other
1162
* http://www.dwheeler.com/essays/scm.html
1164
Good analysis; should try to address everything there in a way he will like.
1168
.. mode: indented-text
1171
.. Would like to use rst-mode, but it's too slow on a document of this
b'\\ No newline at end of file'
added
removed
doc/design.txt
