~bzr-pqm/bzr/bzr.dev

***********************

Reference for Bazaar-NG

***********************

:Author: Martin Pool

:Copyright: Copyright 2004, 2005 Martin Pool; GNU GPL v2

.. contents::

Generalities

------------

Note that this document refers to many features which are not

implemented yet.  Some may never be implemented.

The top level command is ``bzr``.  Everything else is invoked as a

subcommand of that, as is common in version control systems.

A source directory containing some files to be versioned is called a

*tree*; this contains a number of *files* and possibly some

subdirectories.  The point of bzr is to keep track of the *versions*

(or *revisions*) of the tree at various points in time.  A sequence of

versions of a tree form a *branch*.  All branches begin with the empty

directory, called the null revision.  Two branches may have some

revisions in common and then *diverge* later -- which is why they're

called branches.  We can distinguish the *working copy* of the files,

which is available for modification, from their previous versions.

Each file has a unique *file-id*, which remains the same for the life

of the file, even when files are renamed.  Files also have a *kind*,

which can currently be *file* or *directory*, and which cannot change

for any file-id.

The difference between two revisions is a *changeset*.  Changesets

include the textual changes to files, the affected file-ids, the date

of the change, the author, the name of the branch.  Changesets have a

globally unique identifier.

A changeset committed to a branch is *local* to that branch; otherwise

it is foreign.  (Note that a changeset may be local to several

different branches if it was created prior to their divergence.)

Changesets may include a note that they *incorporate* other

changesets; this is used when changes are merged from one branch into

another.  After changes have been merged but before they are committed

they are listed as *pending merges*; when they are committed they are

listed within their changeset.

All files in a versioned directory can be divided into four classes:

Versioned

  Anything assigned a file-id.  Changes to these files are tracked.

Control

  Anything under ``.bzr/``.  Should not be edited by users.

Ignored

  Anything matching an ignore pattern.  As the name suggests, ignored

  by Bazaar.

Unknown

  Everything else.  Generally ignored, except that they are reported

  as 'unknown' and can be added by a recursive add_.

We say a tree, or a file, is *unmodified* if it is the same as in the

most recent version, or *modified* otherwise.

*Committing* creates a new revision equal to the current state of the

tree.  Immediately after committing, all files are unmodified, since

they are the same as the just-committed state.

File states

-----------

A file is in exactly one of these *states*.  These are identified by

single characters which should be familiar to people used to svn/cvs.

?, Unknown

    Not versioned, ignored, or control.

    Typically new files that should be versioned or

    ignored but have not been marked as either yet.

., Up-to-date

    This versioned file is the same as in the last revision on this

    branch.  (The file had the same name and text and properties in

    the previous revision.)

A, Added

    This file will be added by the next commit.  (The file ID was not

    present in the previous revision.)

M, Modified

    This file has been changed from the previous revision and will be

    recorded in the next commit.  (The file had the same name but

    different text in the previous revision.)  Directories have no 

    text and so can never be in this state.

D, Deleted

    This file has been removed from the inventory or deleted in the 

    working copy and will be removed in the next revision.

R, Renamed

    This file had a different name in the previous revision; the next

    commit will record the new name.  The file text may also have been

    modified.

These are only summaries, not complete descriptions.  For example the

'D' state does not distinguish between a file removed by the remove_

command and one whose text has been deleted.  (There should perhaps be

a variation of the ``info`` command, or a ``file-info`` that shows

enough details.)

A directory may be up-to-date even if some files inside it have

different states.

.. _pinned: pinned.html

Global options

--------------

These can be applied to many or all commands.

--help     Show help, either globally or for the selected command.

-v, --verbose  Show progress/explanatory information.  This is good if

               for example using a slow network and you want to see

               that something is happening.

--debug    Show way too much detail about files being opened, locking,

           etc.  Intended for

--silent   Show nothing but errors.  (Perhaps unnecessary; you could

           just redirect stdout to /dev/null.)

--version  Show version and quit.

--dry-run         Show what would be done, but don't make any

                  permanent changes.

--directory DIR   Operate in given directory rather than cwd.

                  (Perhaps this should be ``-d``, but that might be

                  better saved for ``--delete``.  Perhaps -b?)

--recurse, -R     When a directory name is given, operate not only on

                  that directory but also any files or directories

                  contained within it.

                  (XXX: Should this be on by default?  It will often

                  be what people want, but also possibly more

                  surprising.  If it is, we will want a

                  ``--no-recurse``.)

--force           Relax safety checks.

--format=FORMAT

   Choose output format; options might include XML, YAML, text.

--id-only

    Only update the inventory, don't touch the working copy.  (May

    need a better name.)

--show-ids

    List file ids, as well as names.

init

----

Create bzr control files in the current directory::

    bzr init

Use this, followed by add_ and then commit_ to import or start a new

project.

add

---

Add one or more files or directories to the branch::

    bzr add FILE...

Each added file is assigned a new file-id, and will be in the Added

state.  They will be recorded in the next commit that covers that

file, and then in the Up-to-date state.

+-------------+-------------------------------------------------+

|File state   |Action                                           |

+=============+=================================================+

|?            |New file id given to file; now in A state        |

+-------------+-------------------------------------------------+

|I            |"Adding previously ignored file"; now in A       |

+-------------+-------------------------------------------------+

|Z, ZM        |Add file with new ID; now in A state.            |

|             |(To get the old ID back, use revert_ on that     |

|             |file.)                                           |

+-------------+-------------------------------------------------+

|U, A, M, R,  |Warning "already added"; no change               |

|RM           |                                                 |

+-------------+-------------------------------------------------+

|!, D         |Error "no such file"; no change                  |

+-------------+-------------------------------------------------+

|#            |Error "cannot add control file"; no change       |

+-------------+-------------------------------------------------+

--id ID

      Add file with given ID rather than a random UUID.  Error if this

      id is assigned to any other file.  (not implemented yet)

--recurse

    Add directory and all Unknown children, recursively.  This

    includes U children of previously-added subdirectories.

    (not implemented yet)

This command will add any new source files, except for those matching

ignore rules::

  $ bzr add --recurse .

(Note: I hope this might satisfy people who are fond of arch

name-based tagging, and who dislike individually adding & removing

files.  All they need to do is set up the appropriate ignore patterns,

then 'add -R .' and they're done.)

remove

------

Make a file no longer be versioned, and record its deletion from the

inventory::

    $ bzr remove FILE...

This does not remove the working copy.  If you wish to both remove the

working copy and unregister the file, you can simply delete it using

regular ``rm``.  This is the opposite of add_.

:State table:

+--------------+--------------------------------------------------+

| File state   | Action                                           |

+==============+==================================================+

| M, R, RM, .  | File to D state.                                 |

+--------------+--------------------------------------------------+

| A            | File back to I or ? state                        |

+--------------+--------------------------------------------------+

| I, ?, Z, ZM  | Error, no change                                 |

+--------------+--------------------------------------------------+

| !            | Change to D                                      |

+--------------+--------------------------------------------------+

| D            | Warning "already deleted"                        |

+--------------+--------------------------------------------------+

| #            | "Cannot remove control file"                     |

+--------------+--------------------------------------------------+

diff

----

Show all changes compared to the pristine as a text changeset.

--full      Include details for even binary files, uuencoded.  Makes the

            diff long but lossless.

export

------

::

    bzr export TO-DIR

Copy the tree, but leave out Bazaar-NG control files.  This includes copying

uncommitted changes.

This is equivalent to copying the branch and then deleting the control

directory (except more efficient).

Should this also delete any other control files like ``.bzrignore``?

status

------

Show which files are added/deleted/modified/unknown/missing/etc, as in

subversion.

Given the ``--check`` option, returns non-zero if there are any

uncommitted changes.

info

----

Display various information items about the branch.  Can be given

various options to pull out particular fields for easier use in

scripts.

Should include:

* branch name

* parent

* number of revisions

* number of files that are versioned/modified/deleted/added/unknown

* number of versioned directories

* branch format version

* number of people who have made commits

* date of last commit

delta

-----

Compute a two-way non-history-sensitive delta from one branch or

version to another.  Basically a smart diff between the two.

(Perhaps this should just be a ``--format`` option to diff_?)

merge

-----

Merge changes in from another branch, and leave them uncommitted in

this tree::

   merge [FROM-BRANCH]

This makes a note of the revisions which were merged.

A range of revisions may be specified to cherry-pick changes from that

branch, or to merge changes only up to a certain point.

Merge refuses to run if there are uncommitted changes unless forced,

so that merged changes don't get mixed up with your own changes.

You can use a merge rather than an update to accomplish any of several

things:

* Merge in a patch, but modify it to either suit your taste or fix

  textual or semantic conflicts.

* Collapse several merged patches into a single changeset.  A feature

  may go through many revisions when being developed on its own

  branch, but you might want to hide that detail when it merges onto a

  main branch.

--revision RANGE  Merge only selected revisions, rather than

                  everything that's not present yet.

Before a merge is committed, it may be reversed with the revert_

command.

sync

----

::

    sync [OTHER-BRANCH]

--revision RANGE  Pull only selected revisions.

Synchronize mirrored branches.

A mirror branch is a branch that strictly follows a parent branch,

without any changes being committed to it.  This is useful in several

ways:

* Moving a backup of a branch onto another machine to protect against

  disk failure or laptop theft.

* Making the complete history of a upstream branch available for

  offline use.

The result is the same as copying the whole branch, but it is more

efficient for remote branches because only newly-added changesets are

moved.   The result is similar to rsync except it respects Bzr locking.

The same command can be used for push mirrors (changesets are moved

from this branch to the other) or pull mirrors (vice versa).  Bzr

automatically determines which to do by looking at which branch has

more patches.   (Perhaps it would be clearer to have separate *push*

and *pull* commands?)

This command can only be used when the history of one branch is a

subset of the other.  If you commit different changes to both

branches, then ``sync`` will say that the branches have diverged and

it will refuse to run.  This command also refuses to run if the

destination branch has any uncommitted changes.  Uncommitted changes

on the origin are not copied.

Method:

* Get the ordered list of change ids on both branches.

* One list should be a prefix of the other; if not, fail.  The shorter

  list will be the destination branch.

* Check the destination has no uncommitted changes.

* For each change present only in the origin, download it to the

  destination, add to the changeset history and update the tree and

  control files.

commit

------

::

   commit MESSAGE [WHAT]

Commit changes from the working copy into the branch.  By default

commits everything, but can be given a list of files directories or

files.

Partial commits (not implemented yet) should ideally be allowed even when the partial thing

you want to commit is an add, delete or rename.  Partial commits are

**not** allowed if patches have been merged in this change.

Method:

* check preconditions

* get log, if not present or given on command line

* re-check preconditions

* calculate diff from pristine to working copy

* store this diff, plus headers, into the patches directory

* add the diff to the list of applied patches

* update pristine tree

Commit can optionally run some pre-commit and post-commit hooks,

passing them the delta which will be applied; this might mail the

delta or apply it to an export and run a test case there.

:State table:

+-------------+-------------------------------------------------+

|File state   |After commit                                     |

+=============+=================================================+

|?, I, #      |Unchanged                                        |

+-------------+-------------------------------------------------+

|A, M, R, RM  |Recorded, U                                      |

+-------------+-------------------------------------------------+

|D            |Gone                                             |

+-------------+-------------------------------------------------+

|Z, ZM        |Recorded, working copy remains as I or ?         |

+-------------+-------------------------------------------------+

|!            |Error "file is missing"; must be deleted or      |

|             |reverted before commit                           |

+-------------+-------------------------------------------------+

lint

----

Check for problems in the working copy.

+-------------+-------------------------------------------------+

|File state   |Lint output                                      |

+=============+=================================================+

|?            |"Unknown file, please add/ignore/remove"         |

+-------------+-------------------------------------------------+

|Z, ZM        |"Zombie file, please add/ignore/remove/revert"   |

+-------------+-------------------------------------------------+

|!            |"File is missing, please recreate, delete or     |

|             |revert."                                         |

+-------------+-------------------------------------------------+

|A, M, D, R,  |No output                                        |

|RM, #, I     |                                                 |

+-------------+-------------------------------------------------+

check

-----

Run various consistency/sanity checks on the branch.  These might

include:

* Make sure all patches named by the inventory exist.

* No patch IDs are duplicated.

* Make sure hash of each patch is correct.

* Starting at zero, apply each patch and make sure it does not

  conflict.

* All files named in inventory are reasonable.

* No file IDs are duplicated in inventory.

* Possibly many more.

* No patches are in both ``patch-history`` and ``merged-patches``.

* The patches in the bag are exactly those listed in ``patch-history``.

Maybe add a separate option to say that you believe the tree is clean.

backout

-------

Reverse the changes made by previous changesets::

   bzr backout REVISION

   bzr backout REV1 REV2

If a single revision is given, that single changeset is backed out.

If two revisions are given, all changes in that range are backed out.

The change that is reversed need not be the most recently committed

change, but if there are revisions after the ones to be reverse which

depend on them this command may cause conflicts.

This undoes the changes but remembers that it was once applied, so it

will not be merged again.  Anyone who pulls from later versions of

this tree will also have that patch reversed.

You can backout a backout patch, etc, which will restore the previous changes.

This leaves the changeset prepared but not committed; after doing this

you should commit it if you want.

You can also backout only the parts of  a changeset touching a

particular file or subdirectory::

  bzr reverse foo.c@31

revert

------

Undo changes to the working copy of files or directories, and discard

any pending merge notes::

  $ bzr revert [FILE...]

If no files are specified, the entire tree is reverted, which is

equivalent to specifying the top-level directory.  In either case, the

list of pending merges is also cleared.

This does not affect history, only the working copy.  A corollary is

that if no changes have been made to the working copy, this does

nothing.

If a file was Modified, it is returned to the last committed state,

reversing changes to the working copy.  If the file has been Added, it

is un-added but the working copy is not removed, so it returns to

either the Unknown or Ignored state.  If the file has been Deleted, it

is resurrected and returns to the Up-to-date state.  If the file is

Unknown, Ignored, or a Control file then it is not changed and a

warning is issued::

  bzr: warning: cannot revert ignored file foo.c

If the file has been Renamed, it is returned to its original name and

any textual changes are reversed.  This may cause an error if the

rename clashes with an existing file::

  bzr: error: cannot revert foo.c to old name bar.c: file exists

If a directory is listed, by default only changes to the directory

itself are undone.

Ideally this would not lose any changes, but rather just set them

aside, so that the revert command would be undoable.  One way is to

follow Arch and write out the discarded changes to a changeset file

which can be either re-applied or discarded at a later date.  This

very nicely allows for arbitrarily nested undo.  A simpler

intermediate mechanism would be to just move the discarded files to

GNU-style tilde backups.

--merges        Clear the list of pending merges.  If files are

                specified, their text is also reverted, otherwise no

                files are changed.

--id-only       Don't touch the working text, only the inventory.

+-------------+-------------------------------------------------+

| File state  | Actions                                         |

+=============+=================================================+

| A           | Returned to ? or I state, working text unchanged|

+-------------+-------------------------------------------------+

| D           | Working copy restored, returned to U            |

+-------------+-------------------------------------------------+

| Z           | Returned to U                                   |

+-------------+-------------------------------------------------+

| ZM          | Working copy restored to previous               |

|             | version, returned to U                          |

+-------------+-------------------------------------------------+

| R           | Moved back to old                               |

|             | name.                                           |

+-------------+-------------------------------------------------+

| RM          | Moved back to old name and restored to previous |

|             | text.                                           |

+-------------+-------------------------------------------------+

|I, #, ?      | "Cannot revert"                                 |

+-------------+-------------------------------------------------+

log

---

Show a log of changes::

    bzr log

By default shows all changes on this branch.

The default format shows merged changes indented under the change that

merged them.

Alternatively changes can be sorted by date disregarding merges, which

shows the order in which they were written not the order they were

merged.  Changes which were merged are flagged as such.  Such an order

is needed for a GNU-style ChangeLog.  The option is comparable to

choosing a threaded or unthreaded display in an email client, and

should perhaps have those names.

Another option is to show just short descriptions of the merged

changes, similar to arch.

The log can be filtered in any of these ways:

* Logs touching a particular file or directory.

* Changes touching a particular file-id, regardless of what name it

  had in the past.

* Changes by a particular author.

* Changes from a particular branch name (not necessarily the same

  branch).

Another option is to also include diffs (which may make it quite

large).

ignore

------

Mark a file pattern to be ignored and not versioned::

    bzr ignore PATTERN

The pattern should be quoted on Unix to protect it against shell

expansion.

The pattern is appended to ``.bzr-ignore``.  This file is created if

it does not already exist, and added if it is not already versioned.

bzr prints a message showing the pattern added so that people can see

where to go to remove it::

    $ bzr ignore \*.pyc

    bzr: notice: created .bzr-ignored

    bzr: notice: added pattern '*.pyc' to .bzr-ignore

    $ bzr status

    A      .bzr-ignore

If the wrong pattern is added it can be removed by either editing

``.bzr-ignore`` or by reverting__ that file.

__ revert_

is

--

Test various predicates against a branch, similar to the Unix shell

``test`` command::

    bzr is TEST [ARGS]

Takes a third-level command:

``clean``

  Tree has no uncommitted changes.

``in-tree``

  Pwd is in a versioned tree.

``in-control-dir``

  Pwd is inside a Bazaar-NG control directory (and therefore should

  not be modified directly).

``tree-top``

  Pwd is the top of a working tree.

protect

-------

(Proposed idea, may not be implemented or may need a better name.)

Sets a voluntary write-protect flag on a branch, to protect against

accidental changes::

    bzr protect

    bzr unprotect

This is typically used on branches functioning as tags, which should

not normally be committed to or updated.

There may, in the future, be a mechanism to allow only particular

users to protect/unprotect a branch.

uncommit

--------

(It is not certain this command will be implemented.)

This command removes the most recent revision from the branch::

    bzr uncommit

This does not affect the working copy, which can be fixed up and a new

commit run.  The new commit will have a different revision ID.

Removal of the revision will not propagate to any other branches.

The command may be repeated to successively remove more and more

revisions.

This command should perhaps have a more obviously dangerous name,

since it can lose information or cause confusion.

By default the revision is removed from the history, but its text is

left in the store, which allows some chance of recovery.

You cannot partially uncommit; you can however uncommit the whole

revision and then re-commit just part of it.

:Use cases:

    `Wrong commit message`_

.. _`Wrong commit message`: use-cases.html#wrong-commit-message

find

----

Finds files, versions, etc in a branch::

   bzr find [OPERATORS]

The behaviour is similar to regular unix *find*, but this understands

about bzr versioning.  Eventually this may gain all the

and/or/grouping options of Unix find, but not yet.

This does not have the quirky syntax of unix find, but rather just

specifies commands as regular words.

Operators:

* ``directory``

* ``file``

* ``unknown``

* ``ignored``

By default the operators are anded together; there is also an ``or``

operator.

If no action is specified, just prints the file name.  Other actions:

``print``

    Print just the filename.

``printf``

    Print various fields about the object, using a formating system.

``exec``

    Execute a command on the file.