Documentation/urls.txt

   1 GIT URLS[[URLS]]
   2 ----------------
   3
   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 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 them).
  12
  13 The native transport (i.e. git:// URL) does no authentication and
  14 should be used with caution on unsecured networks.
  15
  16 The following syntaxes may be used with them:
  17
  18 - ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
  19 - ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
  20 - ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
  21 - ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
  22
  23 An alternative scp-like syntax may also be used with the ssh protocol:
  24
  25 - {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
  26
  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.
  32
  33 The ssh and git protocols additionally support ++~++__<username>__ expansion:
  34
  35 - ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
  36 - ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
  37 - {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
  38
  39 For local repositories, also supported by Git natively, the following
  40 syntaxes may be used:
  41
  42 - `/path/to/repo.git/`
  43 - ++file:///path/to/repo.git/++
  44
  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[]
  50
  51 ifdef::git-clone[]
  52 These two syntaxes are mostly equivalent, except the former implies
  53 `--local` option.
  54 endif::git-clone[]
  55
  56 `git clone`, `git fetch` and `git pull`, but not `git push`, will also
  57 accept a suitable bundle file. See linkgit:git-bundle[1].
  58
  59 When Git doesn't know how to handle a certain transport protocol, it
  60 attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
  61 exists. To explicitly request a remote helper, the following syntax
  62 may be used:
  63
  64 - _<transport>_::__<address>__
  65
  66 where _<address>_ may be a path, a server and path, or an arbitrary
  67 URL-like string recognized by the specific remote helper being
  68 invoked. See linkgit:gitremote-helpers[7] for details.
  69
  70 If there are a large number of similarly-named remote repositories and
  71 you want to use a different format for them (such that the URLs you
  72 use will be rewritten into URLs that work), you can create a
  73 configuration section of the form:
  74
  75 [verse]
  76 --
  77         [url "__<actual-url-base>__"]
  78                 insteadOf = _<other-url-base>_
  79 --
  80
  81 For example, with this:
  82
  83 ------------
  84         [url "git://git.host.xz/"]
  85                 insteadOf = host.xz:/path/to/
  86                 insteadOf = work:
  87 ------------
  88
  89 a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
  90 rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".
  91
  92 If you want to rewrite URLs for push only, you can create a
  93 configuration section of the form:
  94
  95 [verse]
  96 --
  97         [url "__<actual-url-base>__"]
  98                 pushInsteadOf = _<other-url-base>_
  99 --
 100
 101 For example, with this:
 102
 103 ------------
 104         [url "ssh://example.org/"]
 105                 pushInsteadOf = git://example.org/
 106 ------------
 107
 108 a URL like "git://example.org/path/to/repo.git" will be rewritten to
 109 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
 110 use the original URL.