~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.