| 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://[<user>@]<host>[:<port>]/<path-to-git-repo>` |
| 19 | - `git://<host>[:<port>]/<path-to-git-repo>` |
| 20 | - `http[s]://<host>[:<port>]/<path-to-git-repo>` |
| 21 | - `ftp[s]://<host>[:<port>]/<path-to-git-repo>` |
| 22 | |
| 23 | An alternative scp-like syntax may also be used with the ssh protocol: |
| 24 | |
| 25 | - `[<user>@]<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://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>` |
| 36 | - `git://<host>[:<port>]/~<user>/<path-to-git-repo>` |
| 37 | - `[<user>@]<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-<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. |