← 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
 
Specifying revisions
2
 
====================
3
 
 
4
 
Revision identifiers and ranges
5
 
-------------------------------
6
 
 
7
 
Bazaar has a very expressive way to specify a revision or a range of revisions.
8
 
To specify a range of revisions, the upper and lower bounds are separated by the
9
 
``..`` symbol. For example::
 
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::
10
17
 
11
18
    $ bzr log -r 1..4
12
19
 
15
22
    $ bzr log -r 1..
16
23
    $ bzr log -r ..4
17
24
 
18
 
Some commands take only one revision, not a range. For example::
 
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::
19
29
 
20
30
    $ bzr cat -r 42 foo.c
21
31
 
22
 
In other cases, a range is required but you want the length of the range to
23
 
be one. For commands where this is relevant, the ``-c`` option is used like this::
24
 
 
25
 
    $ bzr diff -c 42
26
 
 
27
 
 
28
 
Available revision identifiers
29
 
------------------------------
30
 
 
31
 
The revision, or the bounds of the range, can be given using
32
 
different format specifications as shown below.
 
32
Available revision specs
 
33
========================
 
34
 
 
35
The revision, or the bounds of the range, can be one of
33
36
 
34
37
 +----------------------+------------------------------------+
35
38
 |  argument type       | description                        |
46
49
 +----------------------+------------------------------------+
47
50
 | **date**:*value*     | first entry after a given date     |
48
51
 +----------------------+------------------------------------+
49
 
 | **tag**:*value*      | revision matching a given tag      |
50
 
 +----------------------+------------------------------------+
51
52
 | **ancestor**:*path*  | last merged revision from a branch |
52
53
 +----------------------+------------------------------------+
53
54
 | **branch**:*path*    | latest revision on another branch  |
54
55
 +----------------------+------------------------------------+
55
 
 | **submit**:*path*    | common ancestor with submit branch |
56
 
 +----------------------+------------------------------------+
57
 
 
58
 
A brief introduction to some of these formats is given below.
59
 
For complete details, see `Revision Identifiers`_ in the
60
 
Bazaar User Reference.
61
 
 
62
 
.. _Revision Identifiers: ../user-reference/bzr_man.html#revision-identifiers
63
56
 
64
57
Numbers
65
 
~~~~~~~
 
58
-------
66
59
 
67
60
Positive numbers denote revision numbers in the current branch. Revision
68
61
numbers are labelled as "revno" in the output of ``bzr log``.  To display
77
70
 
78
71
    $ bzr log -r -10..
79
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
 
80
82
revid
81
 
~~~~~
 
83
-----
82
84
 
83
85
**revid** allows specifying a an internal revision ID, as shown by ``bzr
84
86
log`` and some other commands.
87
89
 
88
90
    $ bzr log -r revid:Matthieu.Moy@imag.fr-20051026185030-93c7cad63ee570df
89
91
 
 
92
 
90
93
before
91
 
~~~~~~
 
94
------
92
95
 
93
96
**before**
94
97
    ''rev'' specifies the leftmost parent of ''rev'', that is the revision
95
98
    that appears before ''rev'' in the revision history, or the revision that
96
 
    was current when ''rev'' was committed.
 
99
    was current when ''rev'' what comitted.
97
100
 
98
101
''rev'' can be any revision specifier and may be chained.
99
102
 
105
108
    ...
106
109
 
107
110
date
108
 
~~~~
 
111
----
109
112
 
110
113
**date**
111
114
    ''value'' matches the first history entry after a given date, either at
125
128
    $ bzr log -r date:yesterday..date:today
126
129
 
127
130
Ancestor
128
 
~~~~~~~~
 
131
--------
129
132
 
130
133
**ancestor**:*path*
131
134
    specifies the common ancestor between the current branch and a 
140
143
    $ bzr diff -r ancestor:../parent
141
144
 
142
145
Branch
143
 
~~~~~~
 
146
------
144
147
 
145
148
branch
146
149
   ``path`` specifies the latest revision in another branch.