← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/revision-syntax.txt

Fix BzrDir.create_workingtree for NULL_REVISION

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