:: The "remote" repository that is the source of a fetch or pull operation, or the destination of a push operation. One of the following notations can be used to name the remote repository: + =============================================================== - Rsync URL: rsync://remote.machine/path/to/repo.git/ - HTTP(s) URL: http://remote.machine/path/to/repo.git/ - git URL: git://remote.machine/path/to/repo.git/ or remote.machine:/path/to/repo.git/ - Local directory: /path/to/repo.git/ =============================================================== + In addition to the above, as a short-hand, the name of a file in `$GIT_DIR/remotes` directory can be given; the named file should be in the following format: + URL: one of the above URL format Push: ... Pull: ... + When such a short-hand is specified in place of without parameters on the command line, ... specified on `Push:` lines or `Pull:` lines are used for `git-push` and `git-fetch`/`git-pull`, respectively. Multiple `Push:` and and `Pull:` lines may be specified for additional branch mappings. + The name of a file in `$GIT_DIR/branches` directory can be specified as an older notation short-hand; the named file should contain a single line, a URL in one of the above formats, optionally followed by a hash `#` and the name of remote head (URL fragment notation). `$GIT_DIR/branches/` file that stores a without the fragment is equivalent to have this in the corresponding file in the `$GIT_DIR/remotes/` directory. + URL: Pull: refs/heads/master: + while having `#` is equivalent to + URL: Pull: refs/heads/: :: The canonical format of a parameter is `+?:`; that is, an optional plus `+`, followed by the source ref, followed by a colon `:`, followed by the destination ref. + When used in `git-push`, the side can be an arbitrary "SHA1 expression" that can be used as an argument to `git-cat-file -t`. E.g. `master~4` (push four parents before the current master head). + For `git-push`, the local ref that matches is used to fast forward the remote ref that matches . If the optional plus `+` is used, the remote ref is updated even if it does not result in a fast forward update. + For `git-fetch` and `git-pull`, the remote ref that matches is fetched, and if is not empty string, the local ref that matches it is fast forwarded using . Again, if the optional plus `+` is used, the local ref is updated even if it does not result in a fast forward update. + [NOTE] If the remote branch from which you want to pull is modified in non-linear ways such as being rewound and rebased frequently, then a pull will attempt a merge with an older version of itself, likely conflict, and fail. It is under these conditions that you would want to use the `+` sign to indicate non-fast-forward updates will be needed. There is currently no easy way to determine or declare that a branch will be made available in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch. + [NOTE] You never do your own development on branches that appear on the right hand side of a colon on `Pull:` lines; they are to be updated by `git-fetch`. The corollary is that a local branch should be introduced and named on a right-hand-side if you intend to do development derived from that branch. This leads to the common `Pull: master:origin` mapping of a remote `master` branch to a local `origin` branch, which is then merged to a local development branch, again typically named `master`. + Some short-cut notations are also supported. + * For backward compatibility, `tag` is almost ignored; it just makes the following parameter to mean a refspec `refs/tags/:refs/tags/`. * A parameter without a colon is equivalent to : when pulling/fetching, and `:` when pushing. That is, do not store it locally if fetching, and update the same name if pushing.