← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/version_info.txt

[merge] robert's knit-performance work

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/version_info.txt
1
 
Exporting version information
2
 
=============================
3
 
 
4
 
Getting the last revision number
5
 
--------------------------------
6
 
 
7
 
If you only need the last revision number in your build scripts, you can
8
 
use the ``revno`` command to get that value like this::
9
 
 
10
 
  $ bzr revno
11
 
  3104
12
 
 
13
 
 
14
 
Getting more version information
15
 
--------------------------------
16
 
 
17
 
The ``version-info`` command can be used to output more information
18
 
about the latest version like this::
19
 
 
20
 
  $ bzr version-info
21
 
  revision-id: pqm@pqm.ubuntu.com-20071211175118-s94sizduj201hrs5
22
 
  date: 2007-12-11 17:51:18 +0000
23
 
  build-date: 2007-12-13 13:14:51 +1000
24
 
  revno: 3104
25
 
  branch-nick: bzr.dev
26
 
 
27
 
You can easily filter that output using operating system tools or
28
 
scripts. For example::
29
 
 
30
 
  $ bzr version-info | grep ^date
31
 
  date: 2007-12-11 17:51:18 +0000
32
 
 
33
 
The ``--all`` option will actually dump version information about
34
 
every revision if you need that information for more advanced
35
 
post-processing.
36
 
 
37
 
 
38
 
Python projects
39
 
---------------
40
 
 
41
 
.. TODO: Figure out how to attach into ``setup.py``
42
 
 
43
 
 
44
 
If using a Makefile to build your project, you can generate the version
45
 
information file as simply as::
46
 
 
47
 
  library/_version.py:
48
 
        bzr version-info --format python > library/_version.py
49
 
 
50
 
This generates a file which contains 3 dictionaries:
51
 
 
52
 
  * `version_info`: A dictionary containing the basic information about the
53
 
    current state.
54
 
 
55
 
  * `revisions`: A dictionary listing all of the revisions in the
56
 
    history of the tree, along with the commit times and commit
57
 
    message.  This defaults to being empty unless ``--all`` or
58
 
    ``--include-history`` is supplied. This is useful if you want to
59
 
    track what bug fixes, etc, might be included in the released
60
 
    version. But for many projects it is more information than needed.
61
 
 
62
 
  * `file_revisions`: A dictionary listing the last-modified revision
63
 
    for all files in the project. This can be used similarly to how
64
 
    ``$Id$`` keywords are used in CVS-controlled files. The last
65
 
    modified date can be determined by looking in the ``revisions``
66
 
    map. This is also empty by default, and enabled only by ``--all``
67
 
    or ``--include-file-revisions``.
68
 
 
69
 
 
70
 
Getting version info in other formats
71
 
-------------------------------------
72
 
 
73
 
Bazaar supports a template-based method for getting version information in
74
 
arbitrary formats.  The ``--custom`` option to ``version-info`` can be
75
 
used by providing a ``--template`` argument that contains variables that
76
 
will be expanded based on the status of the working tree.  For example, to
77
 
generate a C header file with a formatted string containing the current
78
 
revision number::
79
 
 
80
 
 bzr version-info --custom \
81
 
      --template="#define VERSION_INFO \"Project 1.2.3 (r{revno})\"\n" \
82
 
      > version_info.h
83
 
 
84
 
where the ``{revno}`` will be replaced by the revision number of the
85
 
working tree.  (If the example above doesn't work on your OS, try
86
 
entering the command all on one line.) For more information on the
87
 
variables that can be used in templates, see `Version Info`_ in the
88
 
Bazaar User Reference.
89
 
 
90
 
.. _Version Info: ../user-reference/index.html#version-info
91
 
 
92
 
Predefined formats for dumping version information in specific languages
93
 
are currently in development. Please contact us on the mailing list about
94
 
your requirements in this area.
95
 
 
96
 
Check clean
97
 
-----------
98
 
 
99
 
Most information about the contents of the project can be cheaply
100
 
determined by just reading the revision entry. However, it can be useful
101
 
to know if the working tree was completely up-to-date when it was
102
 
packaged, or if there was a local modification. By supplying either
103
 
``--all`` or ``--check-clean``, ``bzr`` will inspect the working tree, and
104
 
set the ``clean`` flag in ``version_info``, as well as set entries in
105
 
``file_revisions`` as ``modified`` where appropriate.
106
 
 
107
 
..
108
 
   vim: tw=74 ft=rst spell spelllang=en_us