1<repository>:: 2 The "remote" repository that is the source of a fetch 3 or pull operation, or the destination of a push operation. 4 One of the following notations can be used 5 to name the remote repository: 6+ 7=============================================================== 8- rsync://host.xz/path/to/repo.git/ 9- http://host.xz/path/to/repo.git/ 10- https://host.xz/path/to/repo.git/ 11- git://host.xz/path/to/repo.git/ 12- ssh://host.xz/path/to/repo.git/ 13- ssh://host.xz/~user/path/to/repo.git/ 14- ssh://host.xz/~/path/to/repo.git 15=============================================================== 16+ 17 SSH Is the default transport protocol and also supports an 18 scp-like syntax. Both syntaxes support username expansion. 19 The following three are identical to the last three above, 20 respectively: 21+ 22=============================================================== 23- host.xz:/path/to/repo.git/ 24- host.xz:~user/path/to/repo.git/ 25- host.xz:path/to/repo.git 26=============================================================== 27+ 28 To sync with a local directory, use: 29 30=============================================================== 31- /path/to/repo.git/ 32=============================================================== 33+ 34In addition to the above, as a short-hand, the name of a 35file in `$GIT_DIR/remotes` directory can be given; the 36named file should be in the following format: 37+ 38 URL: one of the above URL format 39 Push: <refspec> 40 Pull: <refspec> 41+ 42When such a short-hand is specified in place of 43<repository> without <refspec> parameters on the command 44line, <refspec> specified on `Push:` lines or `Pull:` 45lines are used for `git-push` and `git-fetch`/`git-pull`, 46respectively. Multiple `Push:` and and `Pull:` lines may 47be specified for additional branch mappings. 48+ 49The name of a file in `$GIT_DIR/branches` directory can be 50specified as an older notation short-hand; the named 51file should contain a single line, a URL in one of the 52above formats, optionally followed by a hash `#` and the 53name of remote head (URL fragment notation). 54`$GIT_DIR/branches/<remote>` file that stores a <url> 55without the fragment is equivalent to have this in the 56corresponding file in the `$GIT_DIR/remotes/` directory. 57+ 58 URL: <url> 59 Pull: refs/heads/master:<remote> 60+ 61while having `<url>#<head>` is equivalent to 62+ 63 URL: <url> 64 Pull: refs/heads/<head>:<remote> 65 66<refspec>:: 67 The canonical format of a <refspec> parameter is 68 `+?<src>:<dst>`; that is, an optional plus `+`, followed 69 by the source ref, followed by a colon `:`, followed by 70 the destination ref. 71+ 72When used in `git-push`, the <src> side can be an 73arbitrary "SHA1 expression" that can be used as an 74argument to `git-cat-file -t`. E.g. `master~4` (push 75four parents before the current master head). 76+ 77For `git-push`, the local ref that matches <src> is used 78to fast forward the remote ref that matches <dst>. If 79the optional plus `+` is used, the remote ref is updated 80even if it does not result in a fast forward update. 81+ 82For `git-fetch` and `git-pull`, the remote ref that matches <src> 83is fetched, and if <dst> is not empty string, the local 84ref that matches it is fast forwarded using <src>. 85Again, if the optional plus `+` is used, the local ref 86is updated even if it does not result in a fast forward 87update. 88+ 89[NOTE] 90If the remote branch from which you want to pull is 91modified in non-linear ways such as being rewound and 92rebased frequently, then a pull will attempt a merge with 93an older version of itself, likely conflict, and fail. 94It is under these conditions that you would want to use 95the `+` sign to indicate non-fast-forward updates will 96be needed. There is currently no easy way to determine 97or declare that a branch will be made available in a 98repository with this behavior; the pulling user simply 99must know this is the expected usage pattern for a branch. 100+ 101[NOTE] 102You never do your own development on branches that appear 103on the right hand side of a <refspec> colon on `Pull:` lines; 104they are to be updated by `git-fetch`. If you intend to do 105development derived from a remote branch `B`, have a `Pull:` 106line to track it (i.e. `Pull: B:remote-B`), and have a separate 107branch `my-B` to do your development on top of it. The latter 108is created by `git branch my-B remote-B` (or its equivalent `git 109checkout -b my-B remote-B`). Run `git fetch` to keep track of 110the progress of the remote side, and when you see something new 111on the remote branch, merge it into your development branch with 112`git pull . remote-B`, while you are on `my-B` branch. 113The common `Pull: master:origin` mapping of a remote `master` 114branch to a local `origin` branch, which is then merged to a 115ocal development branch, again typically named `master`, is made 116when you run `git clone` for you to follow this pattern. 117+ 118[NOTE] 119There is a difference between listing multiple <refspec> 120directly on `git-pull` command line and having multiple 121`Pull:` <refspec> lines for a <repository> and running 122`git-pull` command without any explicit <refspec> parameters. 123<refspec> listed explicitly on the command line are always 124merged into the current branch after fetching. In other words, 125if you list more than one remote refs, you would be making 126an Octopus. While `git-pull` run without any explicit <refspec> 127parameter takes default <refspec>s from `Pull:` lines, it 128merges only the first <refspec> found into the current branch, 129after fetching all the remote refs. This is because making an 130Octopus from remote refs is rarely done, while keeping track 131of multiple remote heads in one-go by fetching more than one 132is often useful. 133+ 134Some short-cut notations are also supported. 135+ 136* For backward compatibility, `tag` is almost ignored; 137 it just makes the following parameter <tag> to mean a 138 refspec `refs/tags/<tag>:refs/tags/<tag>`. 139* A parameter <ref> without a colon is equivalent to 140 <ref>: when pulling/fetching, and <ref>`:`<ref> when 141 pushing. That is, do not store it locally if 142 fetching, and update the same name if pushing. 143