Documentation/urls: Rewrite to accomodate <transport>::<address>
Rewrite the first part of the document to explicitly show differences between the URLs that can be used with different transport protocols. Mention <transport>::<address> format to explicitly invoke a remote helper. Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ramkumar Ramachandra committed
Apr 6, 2010 at 14:08 UTC
5ce4f4e3bf9894ae5a00c7b4f0ba7ba6d953b008
1 file changed
+36
-23
Documentation/urls.txt
+36
-23
@@ -1,44 +1,57 @@
1
GIT URLS[[URLS]]
2
----------------
3
4
-One of the following notations can be used
5
-to name the remote repository:
4
+In general, URLs contain information about the transport protocol, the
5
+address of the remote server, and the path to the repository.
6
+Depending on the transport protocol, some of this information may be
7
+absent.
8
+
9
+Git natively supports ssh, git, http, https, ftp, ftps, and rsync
10
+protocols. The following syntaxes may be used with them:
11
7
-- rsync://host.xz/path/to/repo.git/
8
-- http://host.xz{startsb}:port{endsb}/path/to/repo.git/
9
-- https://host.xz{startsb}:port{endsb}/path/to/repo.git/
10
-- git://host.xz{startsb}:port{endsb}/path/to/repo.git/
11
-- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/
12
- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/
13
-- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/
14
-- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/
15
-- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git
13
+- git://host.xz{startsb}:port{endsb}/path/to/repo.git/
14
+- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
15
+- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
16
+- rsync://host.xz/path/to/repo.git/
17
17
-SSH is the default transport protocol over the network. You can
18
-optionally specify which user to log-in as, and an alternate,
19
-scp-like syntax is also supported. Both syntaxes support
20
-username expansion, as does the native git protocol, but
21
-only the former supports port specification. The following
22
-three are identical to the last three above, respectively:
18
+An alternative scp-like syntax may also be used with the ssh protocol:
19
24
-- {startsb}user@{endsb}host.xz:/path/to/repo.git/
25
-- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/
26
-- {startsb}user@{endsb}host.xz:path/to/repo.git
20
+- {startsb}user@{endsb}host.xz:path/to/repo.git/
21
28
-To sync with a local directory, you can use:
22
+The ssh and git protocols additionally support ~username expansion:
23
+
24
+- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/
25
+- git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/
26
+- {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/
27
+
28
+For local respositories, also supported by git natively, the following
29
+syntaxes may be used:
30
31
- /path/to/repo.git/
32
- file:///path/to/repo.git/
33
34
ifndef::git-clone[]
34
-They are mostly equivalent, except when cloning. See
35
-linkgit:git-clone[1] for details.
35
+These two syntaxes are mostly equivalent, except when cloning, when
36
+the former implies --local option. See linkgit:git-clone[1] for
37
+details.
38
endif::git-clone[]
39
40
ifdef::git-clone[]
39
-They are equivalent, except the former implies --local option.
41
+These two syntaxes are mostly equivalent, except the former implies
42
+--local option.
43
endif::git-clone[]
44
45
+When git doesn't know how to handle a certain transport protocol, it
46
+attempts to use the 'remote-<transport>' remote helper, if one
47
+exists. To explicitly request a remote helper, the following syntax
48
+may be used:
49
+
50
+- <transport>::<address>
51
+
52
+where <address> may be a path, a server and path, or an arbitrary
53
+URL-like string recognized by the specific remote helper being
54
+invoked. See linkgit:git-remote-helpers[1] for details.
55
56
If there are a large number of similarly-named remote repositories and
57
you want to use a different format for them (such that the URLs you