← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/revision-syntax.txt

merge merge tweaks from aaron, which includes latest .dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/revision-syntax.txt
 
1
Syntax for identifying revisions
 
2
********************************
 
3
 
 
4
There seem to be two main options: use a separate ``-r`` option, or
 
5
put a revision identifier within the filename.
 
6
 
 
7
``-r`` options are familiar from CVS and Subversion, and easy to
 
8
specify, and cover almost all situations.
 
9
 
 
10
Special identifiers in the filename are sometimes more concise, and
 
11
allow for more complete specification of filenames in the presence of
 
12
renames.  They may be more complex to implement, and will cause some
 
13
filenames to be either forbidden or to require escaping.
 
14
 
 
15
----
 
16
 
 
17
 
 
18
How to interpret revisions in the presence of renamed files?  Suppose
 
19
hello.c was renamed in r3; when we do ``bzr diff -r2 hello.c`` should
 
20
we compare to 
 
21
 
 
22
* the file currently called ``hello.c``, as it was in revision 2, even
 
23
  if it then had a different name
 
24
 
 
25
or
 
26
 
 
27
* the file that was called ``hello.c`` in revision 2, even if that is
 
28
  a different file-id?
 
29
 
 
30
Often only one will work, but it is possible to have situations where
 
31
in revision 2 there was a file called ``hello.c`` but it is not the
 
32
same one that now has that name.
 
33
 
 
34
If we can have a simple syntax that accomodates either that would be
 
35
good.  One might be to mix revision numbers into the path, rather than
 
36
a separate ``-r`` option.  For example::
 
37
 
 
38
   hello.c@2
 
39
   @2/hello.c
 
40
 
 
41
   src/@2/hello.c
 
42
 
 
43
The simplest case is to just append the number, but you can vary
 
44
them.  It might even be possible to chain them, getting the file id
 
45
from one revision and its state from another:
 
46
 
 
47
  @70/hello.c@31
 
48
 
 
49
This means "the file that was called ``hello.c`` in revision 70, give
 
50
me its state in revision 31."  (If you wanted to do this across
 
51
branches, I think you might need to get the file id and then look it
 
52
up, etc.)
 
53
 
 
54
Some more syntax: you can refer to a revision by its hash just by
 
55
specifying that; we can distinguish them from anything else by their
 
56
length::
 
57
 
 
58
  hello.c@09fac8dbfd27bd9b4d23a00eb648aa751789536d 
 
59
 
 
60
(Is that really safe?  Perhaps some punctuation is needed to
 
61
distinguish it from a label.  But then I think people should rarely or
 
62
never use them; perhaps it need not be allowed at all.)
 
63
 
 
64
You can also give a date, which is used to find the most recent
 
65
revision no later than that date::
 
66
 
 
67
  hello.c@{2004-12-01}
 
68
  hello.c@{yesterday}
 
69
  ./@{10:30}/
 
70
 
 
71
(Braces can be a bit scary for shell, but if there are no commas they
 
72
are somewhat safe.)
 
73
 
 
74
Or, once we have labels, you can use a label::
 
75
 
 
76
  hello.c@release-2.2
 
77