« back to all changes in this revision
Viewing changes to doc/cmdref.txt
- browse files at revision 1580
- compare with another revision
- compare with revision 5452
- download diff
- download tarball
- view history from revision 1580
- Committer: Canonical.com Patch Queue Manager
- Date: 2006-02-25 17:15:42 UTC
- mfrom: (1575.1.1 bzr.mbp.remove-docs)
- Revision ID: pqm@pqm.ubuntu.com-20060225171542-6a7c8869b0b4003a
remove obsolete docs
- files removed:
- doc/Makefile
added
removed
doc/cmdref.txt
1
***********************
2
Reference for Bazaar-NG
3
***********************
4
5
:Author: Martin Pool
6
:Copyright: Copyright 2004, 2005 Martin Pool; GNU GPL v2
7
8
.. contents::
9
10
11
12
Generalities
13
------------
14
15
Note that this document refers to many features which are not
16
implemented yet. Some may never be implemented.
17
18
The top level command is ``bzr``. Everything else is invoked as a
19
subcommand of that, as is common in version control systems.
20
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.
30
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
34
for any file-id.
35
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.
40
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.)
44
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.
50
51
All files in a versioned directory can be divided into four classes:
52
53
Versioned
54
Anything assigned a file-id. Changes to these files are tracked.
55
Control
56
Anything under ``.bzr/``. Should not be edited by users.
57
Ignored
58
Anything matching an ignore pattern. As the name suggests, ignored
59
by Bazaar.
60
Unknown
61
Everything else. Generally ignored, except that they are reported
62
as 'unknown' and can be added by a recursive add_.
63
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.
66
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.
70
71
72
73
74
File states
75
-----------
76
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.
79
80
?, Unknown
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.
84
., Up-to-date
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.)
88
A, Added
89
This file will be added by the next commit. (The file ID was not
90
present in the previous revision.)
91
M, Modified
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.
96
D, Deleted
97
This file has been removed from the inventory or deleted in the
98
working copy and will be removed in the next revision.
99
R, Renamed
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
102
modified.
103
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
108
enough details.)
109
110
A directory may be up-to-date even if some files inside it have
111
different states.
112
113
.. _pinned: pinned.html
114
115
116
117
Global options
118
--------------
119
120
These can be applied to many or all commands.
121
122
--help Show help, either globally or for the selected command.
123
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.
127
128
--debug Show way too much detail about files being opened, locking,
129
etc. Intended for
130
131
--silent Show nothing but errors. (Perhaps unnecessary; you could
132
just redirect stdout to /dev/null.)
133
134
--version Show version and quit.
135
136
--dry-run Show what would be done, but don't make any
137
permanent changes.
138
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?)
142
143
--recurse, -R When a directory name is given, operate not only on
144
that directory but also any files or directories
145
contained within it.
146
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
150
``--no-recurse``.)
151
152
--force Relax safety checks.
153
154
--format=FORMAT
155
Choose output format; options might include XML, YAML, text.
156
157
--id-only
158
Only update the inventory, don't touch the working copy. (May
159
need a better name.)
160
161
--show-ids
162
List file ids, as well as names.
163
164
165
166
init
167
----
168
169
Create bzr control files in the current directory::
170
171
bzr init
172
173
Use this, followed by add_ and then commit_ to import or start a new
174
project.
175
176
177
178
add
179
---
180
181
Add one or more files or directories to the branch::
182
183
bzr add FILE...
184
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.
188
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 |
198
| |file.) |
199
+-------------+-------------------------------------------------+
200
|U, A, M, R, |Warning "already added"; no change |
201
|RM | |
202
+-------------+-------------------------------------------------+
203
|!, D |Error "no such file"; no change |
204
+-------------+-------------------------------------------------+
205
|# |Error "cannot add control file"; no change |
206
+-------------+-------------------------------------------------+
207
208
--id ID
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)
211
212
--recurse
213
Add directory and all Unknown children, recursively. This
214
includes U children of previously-added subdirectories.
215
(not implemented yet)
216
217
This command will add any new source files, except for those matching
218
ignore rules::
219
220
$ bzr add --recurse .
221
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.)
226
227
228
remove
229
------
230
231
Make a file no longer be versioned, and record its deletion from the
232
inventory::
233
234
$ bzr remove FILE...
235
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_.
239
240
:State table:
241
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
+--------------+--------------------------------------------------+
251
| ! | Change to D |
252
+--------------+--------------------------------------------------+
253
| D | Warning "already deleted" |
254
+--------------+--------------------------------------------------+
255
| # | "Cannot remove control file" |
256
+--------------+--------------------------------------------------+
257
258
259
260
diff
261
----
262
263
Show all changes compared to the pristine as a text changeset.
264
265
--full Include details for even binary files, uuencoded. Makes the
266
diff long but lossless.
267
268
269
270
export
271
------
272
273
::
274
275
bzr export TO-DIR
276
277
Copy the tree, but leave out Bazaar-NG control files. This includes copying
278
uncommitted changes.
279
280
This is equivalent to copying the branch and then deleting the control
281
directory (except more efficient).
282
283
Should this also delete any other control files like ``.bzrignore``?
284
285
286
287
status
288
------
289
290
Show which files are added/deleted/modified/unknown/missing/etc, as in
291
subversion.
292
293
Given the ``--check`` option, returns non-zero if there are any
294
uncommitted changes.
295
296
297
298
info
299
----
300
301
Display various information items about the branch. Can be given
302
various options to pull out particular fields for easier use in
303
scripts.
304
305
Should include:
306
307
* branch name
308
* parent
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
315
316
317
318
delta
319
-----
320
321
Compute a two-way non-history-sensitive delta from one branch or
322
version to another. Basically a smart diff between the two.
323
324
(Perhaps this should just be a ``--format`` option to diff_?)
325
326
327
328
merge
329
-----
330
331
Merge changes in from another branch, and leave them uncommitted in
332
this tree::
333
334
merge [FROM-BRANCH]
335
336
This makes a note of the revisions which were merged.
337
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.
340
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.
343
344
You can use a merge rather than an update to accomplish any of several
345
things:
346
347
* Merge in a patch, but modify it to either suit your taste or fix
348
textual or semantic conflicts.
349
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
353
main branch.
354
355
--revision RANGE Merge only selected revisions, rather than
356
everything that's not present yet.
357
358
Before a merge is committed, it may be reversed with the revert_
359
command.
360
361
362
363
sync
364
----
365
366
::
367
368
sync [OTHER-BRANCH]
369
370
--revision RANGE Pull only selected revisions.
371
372
Synchronize mirrored branches.
373
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
376
ways:
377
378
* Moving a backup of a branch onto another machine to protect against
379
disk failure or laptop theft.
380
381
* Making the complete history of a upstream branch available for
382
offline use.
383
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.
387
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?)
393
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.
400
401
Method:
402
403
* Get the ordered list of change ids on both branches.
404
405
* One list should be a prefix of the other; if not, fail. The shorter
406
list will be the destination branch.
407
408
* Check the destination has no uncommitted changes.
409
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
412
control files.
413
414
415
416
commit
417
------
418
419
::
420
421
commit MESSAGE [WHAT]
422
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
425
files.
426
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.
430
431
Method:
432
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
440
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.
444
445
:State table:
446
447
+-------------+-------------------------------------------------+
448
|File state |After commit |
449
+=============+=================================================+
450
|?, I, # |Unchanged |
451
+-------------+-------------------------------------------------+
452
|A, M, R, RM |Recorded, U |
453
+-------------+-------------------------------------------------+
454
|D |Gone |
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
+-------------+-------------------------------------------------+
461
462
463
464
lint
465
----
466
467
Check for problems in the working copy.
468
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 |
477
| |revert." |
478
+-------------+-------------------------------------------------+
479
|A, M, D, R, |No output |
480
|RM, #, I | |
481
+-------------+-------------------------------------------------+
482
483
484
485
check
486
-----
487
488
Run various consistency/sanity checks on the branch. These might
489
include:
490
491
* Make sure all patches named by the inventory exist.
492
493
* No patch IDs are duplicated.
494
495
* Make sure hash of each patch is correct.
496
497
* Starting at zero, apply each patch and make sure it does not
498
conflict.
499
500
* All files named in inventory are reasonable.
501
502
* No file IDs are duplicated in inventory.
503
504
* Possibly many more.
505
506
* No patches are in both ``patch-history`` and ``merged-patches``.
507
508
* The patches in the bag are exactly those listed in ``patch-history``.
509
510
Maybe add a separate option to say that you believe the tree is clean.
511
512
513
514
backout
515
-------
516
517
Reverse the changes made by previous changesets::
518
519
bzr backout REVISION
520
bzr backout REV1 REV2
521
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.
524
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.
528
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.
532
533
You can backout a backout patch, etc, which will restore the previous changes.
534
535
This leaves the changeset prepared but not committed; after doing this
536
you should commit it if you want.
537
538
You can also backout only the parts of a changeset touching a
539
particular file or subdirectory::
540
541
bzr reverse foo.c@31
542
543
544
revert
545
------
546
547
Undo changes to the working copy of files or directories, and discard
548
any pending merge notes::
549
550
$ bzr revert [FILE...]
551
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.
555
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
558
nothing.
559
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
566
warning is issued::
567
568
bzr: warning: cannot revert ignored file foo.c
569
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::
573
574
bzr: error: cannot revert foo.c to old name bar.c: file exists
575
576
If a directory is listed, by default only changes to the directory
577
itself are undone.
578
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.
586
587
--merges Clear the list of pending merges. If files are
588
specified, their text is also reverted, otherwise no
589
files are changed.
590
591
--id-only Don't touch the working text, only the inventory.
592
593
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 |
607
| | name. |
608
+-------------+-------------------------------------------------+
609
| RM | Moved back to old name and restored to previous |
610
| | text. |
611
+-------------+-------------------------------------------------+
612
|I, #, ? | "Cannot revert" |
613
+-------------+-------------------------------------------------+
614
615
616
log
617
---
618
619
Show a log of changes::
620
621
bzr log
622
623
By default shows all changes on this branch.
624
625
The default format shows merged changes indented under the change that
626
merged them.
627
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.
634
635
Another option is to show just short descriptions of the merged
636
changes, similar to arch.
637
638
The log can be filtered in any of these ways:
639
640
* Logs touching a particular file or directory.
641
642
* Changes touching a particular file-id, regardless of what name it
643
had in the past.
644
645
* Changes by a particular author.
646
647
* Changes from a particular branch name (not necessarily the same
648
branch).
649
650
Another option is to also include diffs (which may make it quite
651
large).
652
653
654
ignore
655
------
656
657
Mark a file pattern to be ignored and not versioned::
658
659
bzr ignore PATTERN
660
661
The pattern should be quoted on Unix to protect it against shell
662
expansion.
663
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::
668
669
$ bzr ignore \*.pyc
670
bzr: notice: created .bzr-ignored
671
bzr: notice: added pattern '*.pyc' to .bzr-ignore
672
$ bzr status
673
A .bzr-ignore
674
675
If the wrong pattern is added it can be removed by either editing
676
``.bzr-ignore`` or by reverting__ that file.
677
678
__ revert_
679
680
681
is
682
--
683
684
Test various predicates against a branch, similar to the Unix shell
685
``test`` command::
686
687
bzr is TEST [ARGS]
688
689
Takes a third-level command:
690
691
``clean``
692
Tree has no uncommitted changes.
693
694
``in-tree``
695
Pwd is in a versioned tree.
696
697
``in-control-dir``
698
Pwd is inside a Bazaar-NG control directory (and therefore should
699
not be modified directly).
700
701
``tree-top``
702
Pwd is the top of a working tree.
703
704
705
protect
706
-------
707
708
(Proposed idea, may not be implemented or may need a better name.)
709
710
Sets a voluntary write-protect flag on a branch, to protect against
711
accidental changes::
712
713
bzr protect
714
bzr unprotect
715
716
This is typically used on branches functioning as tags, which should
717
not normally be committed to or updated.
718
719
There may, in the future, be a mechanism to allow only particular
720
users to protect/unprotect a branch.
721
722
723
uncommit
724
--------
725
726
(It is not certain this command will be implemented.)
727
728
This command removes the most recent revision from the branch::
729
730
bzr uncommit
731
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.
734
735
Removal of the revision will not propagate to any other branches.
736
737
The command may be repeated to successively remove more and more
738
revisions.
739
740
This command should perhaps have a more obviously dangerous name,
741
since it can lose information or cause confusion.
742
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.
745
746
You cannot partially uncommit; you can however uncommit the whole
747
revision and then re-commit just part of it.
748
749
:Use cases:
750
`Wrong commit message`_
751
752
753
.. _`Wrong commit message`: use-cases.html#wrong-commit-message
754
755
756
757
find
758
----
759
760
Finds files, versions, etc in a branch::
761
762
bzr find [OPERATORS]
763
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.
767
768
This does not have the quirky syntax of unix find, but rather just
769
specifies commands as regular words.
770
771
Operators:
772
773
* ``directory``
774
* ``file``
775
* ``unknown``
776
* ``ignored``
777
778
By default the operators are anded together; there is also an ``or``
779
operator.
780
781
If no action is specified, just prints the file name. Other actions:
782
783
``print``
784
Print just the filename.
785
``printf``
786
Print various fields about the object, using a formating system.
787
``exec``
788
Execute a command on the file.
789
Loggerhead is a web-based interface for Breezy
Version: 2.0.1