← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/specifying_revisions.txt

  • Committer: John Arbash Meinel
  • Date: 2006-09-12 22:16:38 UTC
  • mto: This revision was merged to the branch mainline in revision 2071.
  • Revision ID: john@arbash-meinel.com-20060912221638-bf11ba3e3f498106
lazy_import diff.py

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
Revision specs and ranges
 
9
=========================
 
10
 
 
11
**bzr** has a very expressive way to specify a revision, or a range of revisions.
 
12
We'll take the example of the **log** command.
 
13
 
 
14
To specify a range of revisions, use for example::
10
15
 
11
16
    $ bzr log -r 1..4
12
17
 
15
20
    $ bzr log -r 1..
16
21
    $ bzr log -r ..4
17
22
 
18
 
Some commands take only one revision, not a range. For example::
 
23
Note::
 
24
    Omitting the lower bound doesn't work on currently released versions.
 
25
 
 
26
Other commands, like **bzr cat** take only one revision, not a range, like::
19
27
 
20
28
    $ bzr cat -r 42 foo.c
21
29
 
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.
 
30
Available revision specs
 
31
========================
 
32
 
 
33
The revision, or the bounds of the range, can be one of
33
34
 
34
35
 +----------------------+------------------------------------+
35
36
 |  argument type       | description                        |
36
37
 +----------------------+------------------------------------+
37
38
 | *number*             | revision number                    |
38
39
 +----------------------+------------------------------------+
39
 
 | **revno**:*number*   | revision number                    |
 
40
 | **revno**:*number*   | positive revision number           |
40
41
 +----------------------+------------------------------------+
41
42
 | **last**:*number*    | negative revision number           |
42
43
 +----------------------+------------------------------------+
43
 
 | *guid*               | globally unique revision id        |
44
 
 +----------------------+------------------------------------+
45
44
 | **revid**:*guid*     | globally unique revision id        |
46
45
 +----------------------+------------------------------------+
47
46
 | **before**:*rev*     | leftmost parent of ''rev''         |
48
47
 +----------------------+------------------------------------+
49
 
 | *date-value*         | first entry after a given date     |
50
 
 +----------------------+------------------------------------+
51
 
 | **date**:*date-value*| first entry after a given date     |
52
 
 +----------------------+------------------------------------+
53
 
 | *tag-name*           | revision matching a given tag      |
54
 
 +----------------------+------------------------------------+
55
 
 | **tag**:*tag-name*   | revision matching a given tag      |
 
48
 | **date**:*value*     | first entry after a given date     |
56
49
 +----------------------+------------------------------------+
57
50
 | **ancestor**:*path*  | last merged revision from a branch |
58
51
 +----------------------+------------------------------------+
59
52
 | **branch**:*path*    | latest revision on another branch  |
60
53
 +----------------------+------------------------------------+
61
 
 | **submit**:*path*    | common ancestor with submit branch |
62
 
 +----------------------+------------------------------------+
63
 
 
64
 
A brief introduction to some of these formats is given below.
65
 
For complete details, see `Revision Identifiers`_ in the
66
 
Bazaar User Reference.
67
 
 
68
 
.. _Revision Identifiers: ../user-reference/bzr_man.html#revision-identifiers
69
54
 
70
55
Numbers
71
 
~~~~~~~
 
56
-------
72
57
 
73
58
Positive numbers denote revision numbers in the current branch. Revision
74
 
numbers are labelled as "revno" in the output of ``bzr log``.  To display
 
59
numbers are labelled as "revno" in the output of **bzr log**.  To display
75
60
the log for the first ten revisions::
76
61
 
77
62
    $ bzr log -r ..10
83
68
 
84
69
    $ bzr log -r -10..
85
70
 
 
71
revno, last
 
72
-----------
 
73
 
 
74
**revno**:*number*
 
75
    The same as *number*, except that negative numbers are not allowed.
 
76
 
 
77
**last**:*number*
 
78
    The same as -''number''. **last:1** means the last commited revision.
 
79
 
86
80
revid
87
 
~~~~~
 
81
-----
88
82
 
89
 
**revid** allows specifying a an internal revision ID, as shown by ``bzr
90
 
log --show-ids`` and some other commands.
 
83
**revid** allows specifying a an internal revision ID, as show by **bzr
 
84
testament** and some other commands.
91
85
 
92
86
For example::
93
87
 
94
88
    $ bzr log -r revid:Matthieu.Moy@imag.fr-20051026185030-93c7cad63ee570df
95
89
 
 
90
 
96
91
before
97
 
~~~~~~
 
92
------
98
93
 
99
94
**before**
100
95
    ''rev'' specifies the leftmost parent of ''rev'', that is the revision
101
96
    that appears before ''rev'' in the revision history, or the revision that
102
 
    was current when ''rev'' was committed.
 
97
    was current when ''rev'' what comitted.
103
98
 
104
 
''rev'' can be any revision specifier and may be chained.
 
99
''rev'' can be any revision specifier.
105
100
 
106
101
For example::
107
102
 
111
106
    ...
112
107
 
113
108
date
114
 
~~~~
 
109
----
115
110
 
116
111
**date**
117
112
    ''value'' matches the first history entry after a given date, either at
131
126
    $ bzr log -r date:yesterday..date:today
132
127
 
133
128
Ancestor
134
 
~~~~~~~~
 
129
--------
135
130
 
136
131
**ancestor**:*path*
137
 
    specifies the common ancestor between the current branch and a
 
132
    specifies the common ancestor between the current branch,and a 
138
133
    different branch. This is the same ancestor that would be used for
139
134
    merging purposes.
140
135
 
141
136
*path* may be the URL of a remote branch, or the file path to a local branch.
142
137
 
143
138
For example, to see what changes were made on a branch since it was forked
144
 
off ``../parent``::
 
139
off **../parent**::
145
140
 
146
141
    $ bzr diff -r ancestor:../parent
147
142
 
148
143
Branch
149
 
~~~~~~
 
144
------
150
145
 
151
146
branch
152
 
   ``path`` specifies the latest revision in another branch.
 
147
   ''path'' specifies the latest revision in another branch.
153
148
 
154
 
``path`` may be the URL of a remote branch, or the file path to a local branch.
 
149
''path'' may be the URL of a remote branch, or the file path to a local branch.
155
150
 
156
151
For example, to get the differences between this and another branch::
157
152