← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/specifying_revisions.txt

  • Committer: Martin Pool
  • Date: 2007-04-04 06:17:31 UTC
  • mto: This revision was merged to the branch mainline in revision 2397.
  • Revision ID: mbp@sourcefrog.net-20070404061731-tt2xrzllqhbodn83
Contents of TODO file moved into bug tracker

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/specifying_revisions.txt
 
1
=============================
 
2
Specifying revision in Bazaar
 
3
=============================
 
4
 
 
5
Description of the subarguments for ``-r`` as used by commands such as
 
6
``bzr log`` and ``bzr merge``.
 
7
 
 
8
You can get the online documentation with ``bzr help revisionspec``.
 
9
 
 
10
Revision specs and ranges
 
11
=========================
 
12
 
 
13
``bzr`` has a very expressive way to specify a revision, or a range of revisions.
 
14
We'll take the example of the ``log`` command.
 
15
 
 
16
To specify a range of revisions, use for example::
 
17
 
 
18
    $ bzr log -r 1..4
 
19
 
 
20
You can omit one bound like::
 
21
 
 
22
    $ bzr log -r 1..
 
23
    $ bzr log -r ..4
 
24
 
 
25
Note:
 
26
    Omitting the lower bound doesn't work on versions of ``bzr`` prior to 0.14.
 
27
 
 
28
Other commands, like ``bzr cat`` take only one revision, not a range, like::
 
29
 
 
30
    $ bzr cat -r 42 foo.c
 
31
 
 
32
Available revision specs
 
33
========================
 
34
 
 
35
The revision, or the bounds of the range, can be one of
 
36
 
 
37
 +----------------------+------------------------------------+
 
38
 |  argument type       | description                        |
 
39
 +----------------------+------------------------------------+
 
40
 | *number*             | revision number                    |
 
41
 +----------------------+------------------------------------+
 
42
 | **revno**:*number*   | positive revision number           |
 
43
 +----------------------+------------------------------------+
 
44
 | **last**:*number*    | negative revision number           |
 
45
 +----------------------+------------------------------------+
 
46
 | **revid**:*guid*     | globally unique revision id        |
 
47
 +----------------------+------------------------------------+
 
48
 | **before**:*rev*     | leftmost parent of ''rev''         |
 
49
 +----------------------+------------------------------------+
 
50
 | **date**:*value*     | first entry after a given date     |
 
51
 +----------------------+------------------------------------+
 
52
 | **ancestor**:*path*  | last merged revision from a branch |
 
53
 +----------------------+------------------------------------+
 
54
 | **branch**:*path*    | latest revision on another branch  |
 
55
 +----------------------+------------------------------------+
 
56
 
 
57
Numbers
 
58
-------
 
59
 
 
60
Positive numbers denote revision numbers in the current branch. Revision
 
61
numbers are labelled as "revno" in the output of ``bzr log``.  To display
 
62
the log for the first ten revisions::
 
63
 
 
64
    $ bzr log -r ..10
 
65
 
 
66
Negative numbers count from the latest revision, -1 is the last committed
 
67
revision.
 
68
 
 
69
To display the log for the last ten revisions::
 
70
 
 
71
    $ bzr log -r -10..
 
72
 
 
73
revno, last
 
74
-----------
 
75
 
 
76
**revno**:*number*
 
77
    The same as *number*, except that negative numbers are not allowed.
 
78
 
 
79
**last**:*number*
 
80
    The same as -''number''. **last:1** means the last commited revision.
 
81
 
 
82
revid
 
83
-----
 
84
 
 
85
**revid** allows specifying a an internal revision ID, as shown by ``bzr
 
86
log`` and some other commands.
 
87
 
 
88
For example::
 
89
 
 
90
    $ bzr log -r revid:Matthieu.Moy@imag.fr-20051026185030-93c7cad63ee570df
 
91
 
 
92
 
 
93
before
 
94
------
 
95
 
 
96
**before**
 
97
    ''rev'' specifies the leftmost parent of ''rev'', that is the revision
 
98
    that appears before ''rev'' in the revision history, or the revision that
 
99
    was current when ''rev'' what comitted.
 
100
 
 
101
''rev'' can be any revision specifier and may be chained.
 
102
 
 
103
For example::
 
104
 
 
105
    $ bzr log -r before:before:4
 
106
    ...
 
107
    revno: 2
 
108
    ...
 
109
 
 
110
date
 
111
----
 
112
 
 
113
**date**
 
114
    ''value'' matches the first history entry after a given date, either at
 
115
    midnight or at a specified time.
 
116
 
 
117
Legal values are:
 
118
 
 
119
 * **yesterday**
 
120
 * **today**
 
121
 * **tomorrow**
 
122
 * A **YYYY-MM-DD** format date.
 
123
 * A **YYYY-MM-DD,HH:MM:SS** format date/time, seconds are optional (note the
 
124
   comma)
 
125
 
 
126
The proper way of saying "give me all the log entries for today" is::
 
127
 
 
128
    $ bzr log -r date:yesterday..date:today
 
129
 
 
130
Ancestor
 
131
--------
 
132
 
 
133
**ancestor**:*path*
 
134
    specifies the common ancestor between the current branch and a 
 
135
    different branch. This is the same ancestor that would be used for
 
136
    merging purposes.
 
137
 
 
138
*path* may be the URL of a remote branch, or the file path to a local branch.
 
139
 
 
140
For example, to see what changes were made on a branch since it was forked
 
141
off ``../parent``::
 
142
 
 
143
    $ bzr diff -r ancestor:../parent
 
144
 
 
145
Branch
 
146
------
 
147
 
 
148
branch
 
149
   ``path`` specifies the latest revision in another branch.
 
150
 
 
151
``path`` may be the URL of a remote branch, or the file path to a local branch.
 
152
 
 
153
For example, to get the differences between this and another branch::
 
154
 
 
155
    $ bzr diff -r branch:http://example.com/bzr/foo.dev
 
156