~bzr-pqm/bzr/bzr.dev

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
Bazaar-NG
*********

..   These documents are formatted as ReStructuredText.  You can    ..
..   convert them to HTML, PDF, etc using the ``python-docutils``   ..
..   package.                                                       ..


*Bazaar-NG* (``bzr``) is a project of `Canonical Ltd`__ to develop an
open source distributed version control system that is powerful,
friendly, and scalable.  The project is at an early stage of
development.

__ http://canonical.com/


**Note:** These documents are in a very preliminary state, and so may
be internally or externally inconsistent or redundant.  Comments are
still very welcome.  Please send them to <mbp@sourcefrog.net>.


For more information, see the homepage at http://bazaar-ng.org/



User documentation
------------------

* `Project overview/introduction <intro.html>`__

* `Command reference <cmdref.html>`__ -- intended to be user
  documentation, and gives the best overview at the moment of what the
  system will feel like to use.  Fairly complete.

* `Quick reference <quickref.html>`__ -- single page description of
  how to use, intended to check it's adequately simple.  Incomplete.

* `FAQ <faq.html>`__ -- mostly user-oriented FAQ.


Requirements and general design
-------------------------------

* `Various purposes of a VCS <purpose.html>`__ -- taking snapshots and
  helping with merges is not the whole story.

* `Requirements <requirements.html>`__

* `Costs <costs.html>`__ of various factors: time, disk, network, etc.

* `Deadly sins <deadly-sins.html>`__ that gcc maintainers suggest we avoid.

* `Overview of the whole design <design.html>`__ and miscellaneous
  small design points.

* `File formats <formats.html>`__

* `Random observations <random.html>`__ that don't fit anywhere else yet.



Design of particular features
-----------------------------

* `Automatic generation of ChangeLogs <changelogs.html>`__

* `Cherry picking <cherry-picking.html>`__ -- merge just selected non-contiguous changes  from a branch.

* `Common changeset format <common-format.html>`__ for  interchange
  format between VCS.

* `Compression <compression.html>`__ of file text for more efficient storage.

* `Config specs <config-specs.html>`__ assemble a tree from several places.

* `Conflicts <conflicts.html>`_ that can occur during merge-like
  operations.

* `Ignored files <ignore.html>`__

* `Recovering from interrupted operations <interrupted.html>`__

* `Inventory command <inventory.html>`__

* `Branch joins <join-branches.html>`__ represent that all the changes
  from one branch are integrated into another.

* `Kill a version <kill-version.html>`__ to fix a broken commit or
  wrong message, or to
  remove confidential information from the history.

* `Hash collisions <hashes.html>`__ and weaknesses, and the security
  implications thereof.

* `Layers <layers.html>`__ within the design

* `Library interface <library-interface.html>`__ for Python.

* `Merge <merge.html>`__

* `Mirroring <mirroring.html>`__

* `Optional edit command <optional-edit.html>`__: sometimes people
  want to make the  working copy read-only, or not present at all.

* `Partial commits <partial-commit.html>`__

* `Patch pools <pool.html>`__ to efficiently store related branches.

* `Revision syntax <revision-syntax.html>`__ -- ``hello.c@12``, etc.

* `Roll-up commits <rollup.html>`__ -- a single revision incorporates
  the changes from several others.

* `Scalability <scalability.html>`__

* `Security <security.html>`__

* `Shared branches <shared-branches.html>`__ maintained by more than
  one person

* `Supportability <supportability.html>`__ -- how to handle any bugs
  or problems in the field.

* `Place tags on revisions for easy reference <tagging.html>`__

* `Detecting unchanged files <unchanged.html>`__
   
* `Merging previously-unrelated branches <unrelated-merge.html>`__

* `Usability principles <usability.html>`__ (very small at the moment)

* `<use-cases.html>`__

* `<web-interface.html>`__

* `<workflow.html>`__ Modelling/controlling flow of patches.

* `<yaml.html>`__ --  Discussion of using YAML_ as a storage or transmission format.

.. _YAML: http://www.yaml.org/



Comparisons to other systems
----------------------------

* `Taxonomy <taxonomy.html>`__: basic questions a VCS must answer.

* `Bitkeeper <bitkeeper.html>`__, the proprietary system used by some
  kernel developers.

* `Aegis <compared-aegis.html>`__, a tool focussed on enforcing
  process and workflow.

* `Codeville <compared-codeville.html>`__ has an intruiging but
  scarcely-documented merge algorithm.

* `CVSNT <compared-cvsnt.html>`__, with more Windows support and some
  merge enhancements.

* `OpenCM <compared-opencm.html>`__, another hash-based tool with a
  good whitepaper.

* `PRCS <compared-prcs.html>`__, a non-distributed inventory-based tool.

* `GNU Arch <todo-from-arch.html>`__, with many pros and cons.

* `Darcs <darcs.html>`__, a merge-focussed tool with good usability.

* `Quilt <quilt.html>`__ -- Andrew Morton's patch scripts, popular with kernel maintainers.

* `Monotone <monotone.html>`__, Graydon Hoare's hash-based distributed system.

* `SVK <svk.html>`__ --     distributed operation stacked on Subversion.

* `Sun Teamware <compared-teamware.html>`__


Project management and organization
-----------------------------------

* `Notes on how to get a VCS adopted <adoption.html>`__

* `Thanks <thanks.html>`__ to various people

* `Extra commands <extra-commands.html>`__ for
  internal/developer/debugger use.

* `Choice of Python as a development language <python.html>`__