Documentation/pull-fetch-param.txt

   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 URL:            rsync://remote.machine/path/to/repo.git/
   9 - HTTP(s) URL:          http://remote.machine/path/to/repo.git/
  10 - git URL:              git://remote.machine/path/to/repo.git/
  11                         or remote.machine:/path/to/repo.git/
  12 - Local directory:      /path/to/repo.git/
  13 ===============================================================
  14 +
  15 In addition to the above, as a short-hand, the name of a
  16 file in `$GIT_DIR/remotes` directory can be given; the
  17 named file should be in the following format:
  18 +
  19         URL: one of the above URL format
  20         Push: <refspec>...
  21         Pull: <refspec>...
  22 +
  23 When such a short-hand is specified in place of
  24 <repository> without <refspec> parameters on the command
  25 line, <refspec>... specified on `Push:` lines or `Pull:`
  26 lines are used for `git-push` and `git-fetch`/`git-pull`,
  27 respectively.  Multiple `Push:` and and `Pull:` lines may
  28 be specified for additional branch mappings.
  29 +
  30 The name of a file in `$GIT_DIR/branches` directory can be
  31 specified as an older notation short-hand; the named
  32 file should contain a single line, a URL in one of the
  33 above formats, optionally followed by a hash `#` and the
  34 name of remote head (URL fragment notation).
  35 `$GIT_DIR/branches/<remote>` file that stores a <url>
  36 without the fragment is equivalent to have this in the
  37 corresponding file in the `$GIT_DIR/remotes/` directory.
  38 +
  39         URL: <url>
  40         Pull: refs/heads/master:<remote>
  41 +
  42 while having `<url>#<head>` is equivalent to
  43 +
  44         URL: <url>
  45         Pull: refs/heads/<head>:<remote>
  46
  47 <refspec>::
  48         The canonical format of a <refspec> parameter is
  49         `+?<src>:<dst>`; that is, an optional plus `+`, followed
  50         by the source ref, followed by a colon `:`, followed by
  51         the destination ref.
  52 +
  53 When used in `git-push`, the <src> side can be an
  54 arbitrary "SHA1 expression" that can be used as an
  55 argument to `git-cat-file -t`.  E.g. `master~4` (push
  56 four parents before the current master head).
  57 +
  58 For `git-push`, the local ref that matches <src> is used
  59 to fast forward the remote ref that matches <dst>.  If
  60 the optional plus `+` is used, the remote ref is updated
  61 even if it does not result in a fast forward update.
  62 +
  63 For `git-fetch` and `git-pull`, the remote ref that matches <src>
  64 is fetched, and if <dst> is not empty string, the local
  65 ref that matches it is fast forwarded using <src>.
  66 Again, if the optional plus `+` is used, the local ref
  67 is updated even if it does not result in a fast forward
  68 update.
  69 +
  70 [NOTE]
  71 If the remote branch from which you want to pull is
  72 modified in non-linear ways such as being rewound and
  73 rebased frequently, then a pull will attempt a merge with
  74 an older version of itself, likely conflict, and fail.
  75 It is under these conditions that you would want to use
  76 the `+` sign to indicate non-fast-forward updates will
  77 be needed.  There is currently no easy way to determine
  78 or declare that a branch will be made available in a
  79 repository with this behavior; the pulling user simply
  80 must know this is the expected usage pattern for a branch.
  81 +
  82 [NOTE]
  83 You never do your own development on branches that appear
  84 on the right hand side of a <refspec> colon on `Pull:` lines;
  85 they are to be updated by `git-fetch`.  The corollary is that
  86 a local branch should be introduced and named on a <refspec>
  87 right-hand-side if you intend to do development derived from
  88 that branch.
  89 This leads to the common `Pull: master:origin` mapping of a
  90 remote `master` branch to a local `origin` branch, which
  91 is then merged to a local development branch, again typically
  92 named `master`.
  93 +
  94 Some short-cut notations are also supported.
  95 +
  96 * For backward compatibility, `tag` is almost ignored;
  97   it just makes the following parameter <tag> to mean a
  98   refspec `refs/tags/<tag>:refs/tags/<tag>`.
  99 * A parameter <ref> without a colon is equivalent to
 100   <ref>: when pulling/fetching, and <ref>`:`<ref> when
 101   pushing.  That is, do not store it locally if
 102   fetching, and update the same name if pushing.
 103