~bzr-pqm/bzr/bzr.dev

Exporting version information

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

Getting the last revision number

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

If you only need the last revision number in your build scripts, you can

use the ``revno`` command to get that value like this::

  $ bzr revno

  3104

Getting more version information

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

The ``version-info`` command can be used to output more information

about the lastest version like this::

  $ bzr version-info

  revision-id: pqm@pqm.ubuntu.com-20071211175118-s94sizduj201hrs5

  date: 2007-12-11 17:51:18 +0000

  build-date: 2007-12-13 13:14:51 +1000

  revno: 3104

  branch-nick: bzr.dev

You can easily filter that output using operating system tools or

scripts. For example (on Linux/Unix)::

  $ bzr version-info | grep ^date

  date: 2007-12-11 17:51:18 +0000

The ``--all`` option will actually dump version information about

every revision if you need that information for more advanced

post-processing.

Python projects

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

.. TODO: Figure out how to attach into ``setup.py``

If using a Makefile to build your project, you can generate the version

information file as simply as::

  library/_version.py:

        bzr version-info --format python > library/_version.py

This generates a file which contains 3 dictionaries:

  * `version_info`: A dictionary containing the basic information about the

    current state.

  * `revisions`: A dictionary listing all of the revisions in the

    history of the tree, along with the commit times and commit

    message.  This defaults to being empty unless ``--all`` or

    ``--include-history`` is supplied. This is useful if you want to

    track what bug fixes, etc, might be included in the released

    version. But for many projects it is more information than needed.

  * `file_revisions`: A dictionary listing the last-modified revision

    for all files in the project. This can be used similarly to how

    ``$Id$`` keywords are used in CVS-controlled files. The last

    modified date can be determined by looking in the ``revisions``

    map. This is also empty by default, and enabled only by ``--all``

    or ``--include-file-revisions``.

Projects in other languages

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

Support for dumping version information in other languages is currently

in development. Please contact us on the mailing list about your

requirements in this area. (As of the Bazaar 1.0 release date, some patches

are available for other languages but are not yet merged into the core product.)

Check clean

-----------

Most information about the contents of the project can be cheaply

determined by just reading the revision entry. However, it can be useful

to know if the working tree was completely up-to-date when it was

packaged, or if there was a local modification. By supplying either

``--all`` or ``--check-clean``, ``bzr`` will inspect the working tree, and

set the ``clean`` flag in ``version_info``, as well as set entries in

``file_revisions`` as ``modified`` where appropriate.

.. 

   vim: tw=74 ft=rst spell spelllang=en_us