← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/version_info.txt

  • Committer: John Arbash Meinel
  • Date: 2006-09-23 19:05:44 UTC
  • mto: This revision was merged to the branch mainline in revision 2036.
  • Revision ID: john@arbash-meinel.com-20060923190544-c3f625a5bc5589ab
paths are always forward slashed for python zipfiles

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/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 (on Linux/Unix)::
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``
 
1
==========================
 
2
Using ``bzr version-info``
 
3
==========================
 
4
 
 
5
Overview
 
6
========
 
7
 
 
8
This document describes ways of using ``bzr version-info`` as part of a
 
9
build routine to embed version information into a final project.
 
10
 
 
11
 
 
12
Python Project
 
13
==============
 
14
 
 
15
TODO: Figure out how to attach into ``setup.py``
42
16
 
43
17
 
44
18
If using a Makefile to build your project, you can generate the version
45
19
information file as simply as::
46
20
 
47
21
  library/_version.py:
48
 
        bzr version-info --format python > library/_version.py
 
22
        bzr version-info --format=python > library/_version.py
49
23
 
50
24
This generates a file which contains 3 dictionaries:
51
25
 
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/bzr_man.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
 
-----------
 
26
  `version_info`: A dictionary containing the basic information about the
 
27
                  current state.
 
28
 
 
29
  revisions: A dictionary listing all of the revisions in the history of
 
30
             the tree, along with the commit times and commit message.
 
31
             This defaults to being empty unless ``--all`` or
 
32
             ``--include-history`` is supplied. This is useful if you
 
33
             want to track what bugfixes, etc, might be included in the
 
34
             released version. But for many projects it is more
 
35
             information than they need.
 
36
 
 
37
  `file_revisions`: A dictionary listing the last-modified revision for
 
38
                    all files in the project. This can be used similarly
 
39
                    to how ``$Id$`` keywords are used in CVS controlled
 
40
                    files. The last modified date can be determined by
 
41
                    looking in the ``revisions`` map. This is also empty by
 
42
                    default, and enabled only by ``--all`` or
 
43
                    ``--include-file-revisions``.
 
44
 
 
45
Check Clean
 
46
===========
98
47
 
99
48
Most information about the contents of the project can be cheaply
100
49
determined by just reading the revision entry. However, it can be useful
104
53
set the ``clean`` flag in ``version_info``, as well as set entries in
105
54
``file_revisions`` as ``modified`` where appropriate.
106
55
 
107
 
..
 
56
.. 
108
57
   vim: tw=74 ft=rst spell spelllang=en_us