← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/specifying_revisions.txt

  • Committer: Marius Kruger
  • Date: 2010-07-10 21:28:56 UTC
  • mto: (5384.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 5385.
  • Revision ID: marius.kruger@enerweb.co.za-20100710212856-uq4ji3go0u5se7hx
* Update documentation
* add NEWS

Show diffs side-by-side

added added

removed removed

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