1
***********************
2
Reference for Bazaar-NG
3
***********************
6
:Copyright: Copyright 2004, 2005 Martin Pool; GNU GPL v2
15
Note that this document refers to many features which are not
16
implemented yet. Some may never be implemented.
18
The top level command is ``bzr``. Everything else is invoked as a
19
subcommand of that, as is common in version control systems.
21
A source directory containing some files to be versioned is called a
22
*tree*; this contains a number of *files* and possibly some
23
subdirectories. The point of bzr is to keep track of the *versions*
24
(or *revisions*) of the tree at various points in time. A sequence of
25
versions of a tree form a *branch*. All branches begin with the empty
26
directory, called the null revision. Two branches may have some
27
revisions in common and then *diverge* later -- which is why they're
28
called branches. We can distinguish the *working copy* of the files,
29
which is available for modification, from their previous versions.
31
Each file has a unique *file-id*, which remains the same for the life
32
of the file, even when files are renamed. Files also have a *kind*,
33
which can currently be *file* or *directory*, and which cannot change
36
The difference between two revisions is a *changeset*. Changesets
37
include the textual changes to files, the affected file-ids, the date
38
of the change, the author, the name of the branch. Changesets have a
39
globally unique identifier.
41
A changeset committed to a branch is *local* to that branch; otherwise
42
it is foreign. (Note that a changeset may be local to several
43
different branches if it was created prior to their divergence.)
45
Changesets may include a note that they *incorporate* other
46
changesets; this is used when changes are merged from one branch into
47
another. After changes have been merged but before they are committed
48
they are listed as *pending merges*; when they are committed they are
49
listed within their changeset.
51
All files in a versioned directory can be divided into four classes:
54
Anything assigned a file-id. Changes to these files are tracked.
56
Anything under ``.bzr/``. Should not be edited by users.
58
Anything matching an ignore pattern. As the name suggests, ignored
61
Everything else. Generally ignored, except that they are reported
62
as 'unknown' and can be added by a recursive add_.
64
We say a tree, or a file, is *unmodified* if it is the same as in the
65
most recent version, or *modified* otherwise.
67
*Committing* creates a new revision equal to the current state of the
68
tree. Immediately after committing, all files are unmodified, since
69
they are the same as the just-committed state.
77
A file is in exactly one of these *states*. These are identified by
78
single characters which should be familiar to people used to svn/cvs.
81
Not versioned, ignored, or control.
82
Typically new files that should be versioned or
83
ignored but have not been marked as either yet.
85
This versioned file is the same as in the last revision on this
86
branch. (The file had the same name and text and properties in
87
the previous revision.)
89
This file will be added by the next commit. (The file ID was not
90
present in the previous revision.)
92
This file has been changed from the previous revision and will be
93
recorded in the next commit. (The file had the same name but
94
different text in the previous revision.) Directories have no
95
text and so can never be in this state.
97
This file has been removed from the inventory or deleted in the
98
working copy and will be removed in the next revision.
100
This file had a different name in the previous revision; the next
101
commit will record the new name. The file text may also have been
104
These are only summaries, not complete descriptions. For example the
105
'D' state does not distinguish between a file removed by the remove_
106
command and one whose text has been deleted. (There should perhaps be
107
a variation of the ``info`` command, or a ``file-info`` that shows
110
A directory may be up-to-date even if some files inside it have
113
.. _pinned: pinned.html
120
These can be applied to many or all commands.
122
--help Show help, either globally or for the selected command.
124
-v, --verbose Show progress/explanatory information. This is good if
125
for example using a slow network and you want to see
126
that something is happening.
128
--debug Show way too much detail about files being opened, locking,
131
--silent Show nothing but errors. (Perhaps unnecessary; you could
132
just redirect stdout to /dev/null.)
134
--version Show version and quit.
136
--dry-run Show what would be done, but don't make any
139
--directory DIR Operate in given directory rather than cwd.
140
(Perhaps this should be ``-d``, but that might be
141
better saved for ``--delete``. Perhaps -b?)
143
--recurse, -R When a directory name is given, operate not only on
144
that directory but also any files or directories
147
(XXX: Should this be on by default? It will often
148
be what people want, but also possibly more
149
surprising. If it is, we will want a
152
--force Relax safety checks.
155
Choose output format; options might include XML, YAML, text.
158
Only update the inventory, don't touch the working copy. (May
162
List file ids, as well as names.
169
Create bzr control files in the current directory::
173
Use this, followed by add_ and then commit_ to import or start a new
181
Add one or more files or directories to the branch::
185
Each added file is assigned a new file-id, and will be in the Added
186
state. They will be recorded in the next commit that covers that
187
file, and then in the Up-to-date state.
189
+-------------+-------------------------------------------------+
190
|File state |Action |
191
+=============+=================================================+
192
|? |New file id given to file; now in A state |
193
+-------------+-------------------------------------------------+
194
|I |"Adding previously ignored file"; now in A |
195
+-------------+-------------------------------------------------+
196
|Z, ZM |Add file with new ID; now in A state. |
197
| |(To get the old ID back, use revert_ on that |
199
+-------------+-------------------------------------------------+
200
|U, A, M, R, |Warning "already added"; no change |
202
+-------------+-------------------------------------------------+
203
|!, D |Error "no such file"; no change |
204
+-------------+-------------------------------------------------+
205
|# |Error "cannot add control file"; no change |
206
+-------------+-------------------------------------------------+
209
Add file with given ID rather than a random UUID. Error if this
210
id is assigned to any other file. (not implemented yet)
213
Add directory and all Unknown children, recursively. This
214
includes U children of previously-added subdirectories.
215
(not implemented yet)
217
This command will add any new source files, except for those matching
220
$ bzr add --recurse .
222
(Note: I hope this might satisfy people who are fond of arch
223
name-based tagging, and who dislike individually adding & removing
224
files. All they need to do is set up the appropriate ignore patterns,
225
then 'add -R .' and they're done.)
231
Make a file no longer be versioned, and record its deletion from the
236
This does not remove the working copy. If you wish to both remove the
237
working copy and unregister the file, you can simply delete it using
238
regular ``rm``. This is the opposite of add_.
242
+--------------+--------------------------------------------------+
243
| File state | Action |
244
+==============+==================================================+
245
| M, R, RM, . | File to D state. |
246
+--------------+--------------------------------------------------+
247
| A | File back to I or ? state |
248
+--------------+--------------------------------------------------+
249
| I, ?, Z, ZM | Error, no change |
250
+--------------+--------------------------------------------------+
252
+--------------+--------------------------------------------------+
253
| D | Warning "already deleted" |
254
+--------------+--------------------------------------------------+
255
| # | "Cannot remove control file" |
256
+--------------+--------------------------------------------------+
263
Show all changes compared to the pristine as a text changeset.
265
--full Include details for even binary files, uuencoded. Makes the
266
diff long but lossless.
277
Copy the tree, but leave out Bazaar-NG control files. This includes copying
280
This is equivalent to copying the branch and then deleting the control
281
directory (except more efficient).
283
Should this also delete any other control files like ``.bzrignore``?
290
Show which files are added/deleted/modified/unknown/missing/etc, as in
293
Given the ``--check`` option, returns non-zero if there are any
301
Display various information items about the branch. Can be given
302
various options to pull out particular fields for easier use in
309
* number of revisions
310
* number of files that are versioned/modified/deleted/added/unknown
311
* number of versioned directories
312
* branch format version
313
* number of people who have made commits
314
* date of last commit
321
Compute a two-way non-history-sensitive delta from one branch or
322
version to another. Basically a smart diff between the two.
324
(Perhaps this should just be a ``--format`` option to diff_?)
331
Merge changes in from another branch, and leave them uncommitted in
336
This makes a note of the revisions which were merged.
338
A range of revisions may be specified to cherry-pick changes from that
339
branch, or to merge changes only up to a certain point.
341
Merge refuses to run if there are uncommitted changes unless forced,
342
so that merged changes don't get mixed up with your own changes.
344
You can use a merge rather than an update to accomplish any of several
347
* Merge in a patch, but modify it to either suit your taste or fix
348
textual or semantic conflicts.
350
* Collapse several merged patches into a single changeset. A feature
351
may go through many revisions when being developed on its own
352
branch, but you might want to hide that detail when it merges onto a
355
--revision RANGE Merge only selected revisions, rather than
356
everything that's not present yet.
358
Before a merge is committed, it may be reversed with the revert_
370
--revision RANGE Pull only selected revisions.
372
Synchronize mirrored branches.
374
A mirror branch is a branch that strictly follows a parent branch,
375
without any changes being committed to it. This is useful in several
378
* Moving a backup of a branch onto another machine to protect against
379
disk failure or laptop theft.
381
* Making the complete history of a upstream branch available for
384
The result is the same as copying the whole branch, but it is more
385
efficient for remote branches because only newly-added changesets are
386
moved. The result is similar to rsync except it respects Bzr locking.
388
The same command can be used for push mirrors (changesets are moved
389
from this branch to the other) or pull mirrors (vice versa). Bzr
390
automatically determines which to do by looking at which branch has
391
more patches. (Perhaps it would be clearer to have separate *push*
392
and *pull* commands?)
394
This command can only be used when the history of one branch is a
395
subset of the other. If you commit different changes to both
396
branches, then ``sync`` will say that the branches have diverged and
397
it will refuse to run. This command also refuses to run if the
398
destination branch has any uncommitted changes. Uncommitted changes
399
on the origin are not copied.
403
* Get the ordered list of change ids on both branches.
405
* One list should be a prefix of the other; if not, fail. The shorter
406
list will be the destination branch.
408
* Check the destination has no uncommitted changes.
410
* For each change present only in the origin, download it to the
411
destination, add to the changeset history and update the tree and
421
commit MESSAGE [WHAT]
423
Commit changes from the working copy into the branch. By default
424
commits everything, but can be given a list of files directories or
427
Partial commits (not implemented yet) should ideally be allowed even when the partial thing
428
you want to commit is an add, delete or rename. Partial commits are
429
**not** allowed if patches have been merged in this change.
433
* check preconditions
434
* get log, if not present or given on command line
435
* re-check preconditions
436
* calculate diff from pristine to working copy
437
* store this diff, plus headers, into the patches directory
438
* add the diff to the list of applied patches
439
* update pristine tree
441
Commit can optionally run some pre-commit and post-commit hooks,
442
passing them the delta which will be applied; this might mail the
443
delta or apply it to an export and run a test case there.
447
+-------------+-------------------------------------------------+
448
|File state |After commit |
449
+=============+=================================================+
450
|?, I, # |Unchanged |
451
+-------------+-------------------------------------------------+
452
|A, M, R, RM |Recorded, U |
453
+-------------+-------------------------------------------------+
455
+-------------+-------------------------------------------------+
456
|Z, ZM |Recorded, working copy remains as I or ? |
457
+-------------+-------------------------------------------------+
458
|! |Error "file is missing"; must be deleted or |
459
| |reverted before commit |
460
+-------------+-------------------------------------------------+
467
Check for problems in the working copy.
469
+-------------+-------------------------------------------------+
470
|File state |Lint output |
471
+=============+=================================================+
472
|? |"Unknown file, please add/ignore/remove" |
473
+-------------+-------------------------------------------------+
474
|Z, ZM |"Zombie file, please add/ignore/remove/revert" |
475
+-------------+-------------------------------------------------+
476
|! |"File is missing, please recreate, delete or |
478
+-------------+-------------------------------------------------+
479
|A, M, D, R, |No output |
481
+-------------+-------------------------------------------------+
488
Run various consistency/sanity checks on the branch. These might
491
* Make sure all patches named by the inventory exist.
493
* No patch IDs are duplicated.
495
* Make sure hash of each patch is correct.
497
* Starting at zero, apply each patch and make sure it does not
500
* All files named in inventory are reasonable.
502
* No file IDs are duplicated in inventory.
504
* Possibly many more.
506
* No patches are in both ``patch-history`` and ``merged-patches``.
508
* The patches in the bag are exactly those listed in ``patch-history``.
510
Maybe add a separate option to say that you believe the tree is clean.
517
Reverse the changes made by previous changesets::
520
bzr backout REV1 REV2
522
If a single revision is given, that single changeset is backed out.
523
If two revisions are given, all changes in that range are backed out.
525
The change that is reversed need not be the most recently committed
526
change, but if there are revisions after the ones to be reverse which
527
depend on them this command may cause conflicts.
529
This undoes the changes but remembers that it was once applied, so it
530
will not be merged again. Anyone who pulls from later versions of
531
this tree will also have that patch reversed.
533
You can backout a backout patch, etc, which will restore the previous changes.
535
This leaves the changeset prepared but not committed; after doing this
536
you should commit it if you want.
538
You can also backout only the parts of a changeset touching a
539
particular file or subdirectory::
547
Undo changes to the working copy of files or directories, and discard
548
any pending merge notes::
550
$ bzr revert [FILE...]
552
If no files are specified, the entire tree is reverted, which is
553
equivalent to specifying the top-level directory. In either case, the
554
list of pending merges is also cleared.
556
This does not affect history, only the working copy. A corollary is
557
that if no changes have been made to the working copy, this does
560
If a file was Modified, it is returned to the last committed state,
561
reversing changes to the working copy. If the file has been Added, it
562
is un-added but the working copy is not removed, so it returns to
563
either the Unknown or Ignored state. If the file has been Deleted, it
564
is resurrected and returns to the Up-to-date state. If the file is
565
Unknown, Ignored, or a Control file then it is not changed and a
568
bzr: warning: cannot revert ignored file foo.c
570
If the file has been Renamed, it is returned to its original name and
571
any textual changes are reversed. This may cause an error if the
572
rename clashes with an existing file::
574
bzr: error: cannot revert foo.c to old name bar.c: file exists
576
If a directory is listed, by default only changes to the directory
579
Ideally this would not lose any changes, but rather just set them
580
aside, so that the revert command would be undoable. One way is to
581
follow Arch and write out the discarded changes to a changeset file
582
which can be either re-applied or discarded at a later date. This
583
very nicely allows for arbitrarily nested undo. A simpler
584
intermediate mechanism would be to just move the discarded files to
585
GNU-style tilde backups.
587
--merges Clear the list of pending merges. If files are
588
specified, their text is also reverted, otherwise no
591
--id-only Don't touch the working text, only the inventory.
594
+-------------+-------------------------------------------------+
595
| File state | Actions |
596
+=============+=================================================+
597
| A | Returned to ? or I state, working text unchanged|
598
+-------------+-------------------------------------------------+
599
| D | Working copy restored, returned to U |
600
+-------------+-------------------------------------------------+
601
| Z | Returned to U |
602
+-------------+-------------------------------------------------+
603
| ZM | Working copy restored to previous |
604
| | version, returned to U |
605
+-------------+-------------------------------------------------+
606
| R | Moved back to old |
608
+-------------+-------------------------------------------------+
609
| RM | Moved back to old name and restored to previous |
611
+-------------+-------------------------------------------------+
612
|I, #, ? | "Cannot revert" |
613
+-------------+-------------------------------------------------+
619
Show a log of changes::
623
By default shows all changes on this branch.
625
The default format shows merged changes indented under the change that
628
Alternatively changes can be sorted by date disregarding merges, which
629
shows the order in which they were written not the order they were
630
merged. Changes which were merged are flagged as such. Such an order
631
is needed for a GNU-style ChangeLog. The option is comparable to
632
choosing a threaded or unthreaded display in an email client, and
633
should perhaps have those names.
635
Another option is to show just short descriptions of the merged
636
changes, similar to arch.
638
The log can be filtered in any of these ways:
640
* Logs touching a particular file or directory.
642
* Changes touching a particular file-id, regardless of what name it
645
* Changes by a particular author.
647
* Changes from a particular branch name (not necessarily the same
650
Another option is to also include diffs (which may make it quite
657
Mark a file pattern to be ignored and not versioned::
661
The pattern should be quoted on Unix to protect it against shell
664
The pattern is appended to ``.bzr-ignore``. This file is created if
665
it does not already exist, and added if it is not already versioned.
666
bzr prints a message showing the pattern added so that people can see
667
where to go to remove it::
670
bzr: notice: created .bzr-ignored
671
bzr: notice: added pattern '*.pyc' to .bzr-ignore
675
If the wrong pattern is added it can be removed by either editing
676
``.bzr-ignore`` or by reverting__ that file.
684
Test various predicates against a branch, similar to the Unix shell
689
Takes a third-level command:
692
Tree has no uncommitted changes.
695
Pwd is in a versioned tree.
698
Pwd is inside a Bazaar-NG control directory (and therefore should
699
not be modified directly).
702
Pwd is the top of a working tree.
708
(Proposed idea, may not be implemented or may need a better name.)
710
Sets a voluntary write-protect flag on a branch, to protect against
716
This is typically used on branches functioning as tags, which should
717
not normally be committed to or updated.
719
There may, in the future, be a mechanism to allow only particular
720
users to protect/unprotect a branch.
726
(It is not certain this command will be implemented.)
728
This command removes the most recent revision from the branch::
732
This does not affect the working copy, which can be fixed up and a new
733
commit run. The new commit will have a different revision ID.
735
Removal of the revision will not propagate to any other branches.
737
The command may be repeated to successively remove more and more
740
This command should perhaps have a more obviously dangerous name,
741
since it can lose information or cause confusion.
743
By default the revision is removed from the history, but its text is
744
left in the store, which allows some chance of recovery.
746
You cannot partially uncommit; you can however uncommit the whole
747
revision and then re-commit just part of it.
750
`Wrong commit message`_
753
.. _`Wrong commit message`: use-cases.html#wrong-commit-message
760
Finds files, versions, etc in a branch::
764
The behaviour is similar to regular unix *find*, but this understands
765
about bzr versioning. Eventually this may gain all the
766
and/or/grouping options of Unix find, but not yet.
768
This does not have the quirky syntax of unix find, but rather just
769
specifies commands as regular words.
778
By default the operators are anded together; there is also an ``or``
781
If no action is specified, just prints the file name. Other actions:
784
Print just the filename.
786
Print various fields about the object, using a formating system.
788
Execute a command on the file.
added
removed
doc/cmdref.txt
