← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/en/url-special-chars.txt

  • Committer: Andrew Starr-Bochicchio
  • Date: 2015-07-31 01:04:41 UTC
  • mto: This revision was merged to the branch mainline in revision 6606.
  • Revision ID: a.starr.b@gmail.com-20150731010441-3domwjjtnjijxlr2
https://launchpad.net/bugs/1480015
Use hexlify() from binascii directly as paramiko removed hexify().

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics/en/url-special-chars.txt
 
1
Special character handling in URLs
 
2
==================================
 
3
 
 
4
Bazaar allows locations to be specified in multiple ways, either:
 
5
 
 
6
 * Fully qualified URLs
 
7
 
 
8
 * File system paths, relative or absolute
 
9
 
 
10
Internally bzr treats all locations as URLs. For any file system paths
 
11
that are specified it will automatically determine the appropriate URL
 
12
representation, and escape special characters where necessary.
 
13
 
 
14
There are a few characters which have special meaning in URLs and need careful
 
15
handling to avoid ambiguities. Characters can be escaped with a % and a hex
 
16
value in URLs. Any non-ASCII characters in a file path will automatically be
 
17
urlencoded when the path is converted to a URL.
 
18
 
 
19
URLs represent non-ASCII characters in an encoding defined by the server, but
 
20
usually UTF-8.  The % escapes should be of the UTF-8 bytes.  Bazaar tries to be
 
21
generous in what it accepts as a URL and to print them in a way that
 
22
will be readable.
 
23
 
 
24
For example, if you have a directory named '/tmp/%2False' these are all valid
 
25
ways of accessing the content (0x2F, or 47, is the ASCII code for forward slash)::
 
26
 
 
27
  cd /tmp
 
28
  bzr log /tmp/%2False
 
29
  bzr log %2False
 
30
  bzr log file:///tmp/%252False
 
31
  bzr log file://localhost/tmp/%252False
 
32
  bzr log file:%252False
 
33
 
 
34
These are valid but do not refer to the same file::
 
35
 
 
36
  bzr log file:///tmp/%2False (refers to a file called /tmp/\/alse)
 
37
  bzr log %252False (refers to a file called /tmp/%252False)
 
38
 
 
39
Comma also has special meaning in URLs, because it denotes `segment parameters`_
 
40
 
 
41
_`segment parameters`: http://www.ietf.org/rfc/rfc3986.txt (section 3.3)
 
42
 
 
43
Comma is also special in any file system paths that are specified. To use a literal
 
44
comma in a file system path, specify a URL and URL encode the comma::
 
45
 
 
46
  bzr log foo,branch=bla # path "foo" with the segment parameter "branch" set to "bla"
 
47
  bzr log file:foo%2Cbranch=bla # path "foo,branch=bla"
 
48
  bzr log file:foo,branch=bla # path "foo" with segment parameter "branch" set to "bla"