~bzr-pqm/bzr/bzr.dev

=============================

Specifying revision in Bazaar

=============================

Description of the subarguments for ``-r`` as used by commands such as

``bzr log`` and ``bzr merge``.

You can get the online documentation with ``bzr help revisionspec``.

Revision specs and ranges

=========================

``bzr`` has a very expressive way to specify a revision, or a range of revisions.

We'll take the example of the ``log`` command.

To specify a range of revisions, use for example::

    $ bzr log -r 1..4

You can omit one bound like::

    $ bzr log -r 1..

    $ bzr log -r ..4

Note:

    Omitting the lower bound doesn't work on versions of ``bzr`` prior to 0.14.

Other commands, like ``bzr cat`` take only one revision, not a range, like::

    $ bzr cat -r 42 foo.c

Available revision specs

========================

The revision, or the bounds of the range, can be one of

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

 |  argument type       | description                        |

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

 | *number*             | revision number                    |

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

 | **revno**:*number*   | positive revision number           |

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

 | **last**:*number*    | negative revision number           |

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

 | **revid**:*guid*     | globally unique revision id        |

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

 | **before**:*rev*     | leftmost parent of ''rev''         |

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

 | **date**:*value*     | first entry after a given date     |

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

 | **ancestor**:*path*  | last merged revision from a branch |

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

 | **branch**:*path*    | latest revision on another branch  |

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

Numbers

-------

Positive numbers denote revision numbers in the current branch. Revision

numbers are labelled as "revno" in the output of ``bzr log``.  To display

the log for the first ten revisions::

    $ bzr log -r ..10

Negative numbers count from the latest revision, -1 is the last committed

revision.

To display the log for the last ten revisions::

    $ bzr log -r -10..

revno, last

-----------

**revno**:*number*

    The same as *number*, except that negative numbers are not allowed.

**last**:*number*

    The same as -''number''. **last:1** means the last commited revision.

revid

-----

**revid** allows specifying a an internal revision ID, as shown by ``bzr

log`` and some other commands.

For example::

    $ bzr log -r revid:Matthieu.Moy@imag.fr-20051026185030-93c7cad63ee570df

before

------

**before**

    ''rev'' specifies the leftmost parent of ''rev'', that is the revision

    that appears before ''rev'' in the revision history, or the revision that

    was current when ''rev'' what comitted.

''rev'' can be any revision specifier and may be chained.

For example::

    $ bzr log -r before:before:4

    ...

    revno: 2

    ...

date

----

**date**

    ''value'' matches the first history entry after a given date, either at

    midnight or at a specified time.

Legal values are:

 * **yesterday**

 * **today**

 * **tomorrow**

 * A **YYYY-MM-DD** format date.

 * A **YYYY-MM-DD,HH:MM:SS** format date/time, seconds are optional (note the

   comma)

The proper way of saying "give me all the log entries for today" is::

    $ bzr log -r date:yesterday..date:today

Ancestor

--------

**ancestor**:*path*

    specifies the common ancestor between the current branch and a 

    different branch. This is the same ancestor that would be used for

    merging purposes.

*path* may be the URL of a remote branch, or the file path to a local branch.

For example, to see what changes were made on a branch since it was forked

off ``../parent``::

    $ bzr diff -r ancestor:../parent

Branch

------

branch

   ``path`` specifies the latest revision in another branch.

``path`` may be the URL of a remote branch, or the file path to a local branch.

For example, to get the differences between this and another branch::

    $ bzr diff -r branch:http://example.com/bzr/foo.dev