|
2022.1.7
by John Arbash Meinel
Add NEWS and a simple doc for using bzr version-info |
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`` |
|
16 |
||
17 |
||
18 |
If using a Makefile to build your project, you can generate the version |
|
19 |
information file as simply as:: |
|
20 |
||
21 |
library/_version.py: |
|
22 |
bzr version-info --format=python > library/_version.py |
|
23 |
||
24 |
This generates a file which contains 3 dictionaries: |
|
25 |
||
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 |
=========== |
|
47 |
||
48 |
Most information about the contents of the project can be cheaply |
|
49 |
determined by just reading the revision entry. However, it can be useful |
|
50 |
to know if the working tree was completely up-to-date when it was |
|
51 |
packaged, or if there was a local modification. By supplying either |
|
52 |
``--all`` or ``--check-clean``, ``bzr`` will inspect the working tree, and |
|
53 |
set the ``clean`` flag in ``version_info``, as well as set entries in |
|
54 |
``file_revisions`` as ``modified`` where appropriate. |
|
55 |
||
56 |
.. |
|
57 |
vim: tw=74 ft=rst spell spelllang=en_us |