doc: describe git svn init --ignore-refs
[git/git-svn.git] / Documentation / urls.txt
blobb05da95788f7b1294be6b2733ca55b58111b7607
1 GIT URLS[[URLS]]
2 ----------------
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.
9 Git supports ssh, git, http, and https protocols (in addition, ftp,
10 and ftps can be used for fetching, but this is inefficient and
11 deprecated; do not use it).
13 The native transport (i.e. git:// URL) does no authentication and
14 should be used with caution on unsecured networks.
16 The following syntaxes may be used with them:
18 - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/
19 - git://host.xz{startsb}:port{endsb}/path/to/repo.git/
20 - http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
21 - ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
23 An alternative scp-like syntax may also be used with the ssh protocol:
25 - {startsb}user@{endsb}host.xz:path/to/repo.git/
27 This syntax is only recognized if there are no slashes before the
28 first colon. This helps differentiate a local path that contains a
29 colon. For example the local path `foo:bar` could be specified as an
30 absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
31 url.
33 The ssh and git protocols additionally support ~username expansion:
35 - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/
36 - git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/
37 - {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/
39 For local repositories, also supported by Git natively, the following
40 syntaxes may be used:
42 - /path/to/repo.git/
43 - \file:///path/to/repo.git/
45 ifndef::git-clone[]
46 These two syntaxes are mostly equivalent, except when cloning, when
47 the former implies --local option. See linkgit:git-clone[1] for
48 details.
49 endif::git-clone[]
51 ifdef::git-clone[]
52 These two syntaxes are mostly equivalent, except the former implies
53 --local option.
54 endif::git-clone[]
56 When Git doesn't know how to handle a certain transport protocol, it
57 attempts to use the 'remote-<transport>' remote helper, if one
58 exists. To explicitly request a remote helper, the following syntax
59 may be used:
61 - <transport>::<address>
63 where <address> may be a path, a server and path, or an arbitrary
64 URL-like string recognized by the specific remote helper being
65 invoked. See linkgit:gitremote-helpers[1] for details.
67 If there are a large number of similarly-named remote repositories and
68 you want to use a different format for them (such that the URLs you
69 use will be rewritten into URLs that work), you can create a
70 configuration section of the form:
72 ------------
73         [url "<actual url base>"]
74                 insteadOf = <other url base>
75 ------------
77 For example, with this:
79 ------------
80         [url "git://git.host.xz/"]
81                 insteadOf = host.xz:/path/to/
82                 insteadOf = work:
83 ------------
85 a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
86 rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".
88 If you want to rewrite URLs for push only, you can create a
89 configuration section of the form:
91 ------------
92         [url "<actual url base>"]
93                 pushInsteadOf = <other url base>
94 ------------
96 For example, with this:
98 ------------
99         [url "ssh://example.org/"]
100                 pushInsteadOf = git://example.org/
101 ------------
103 a URL like "git://example.org/path/to/repo.git" will be rewritten to
104 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
105 use the original URL.