Documentation/git-pull.txt

   1 git-pull(1)
   2 ===========
   3
   4 NAME
   5 ----
   6 git-pull - Pull and merge from another repository.
   7
   8
   9 SYNOPSIS
  10 --------
  11 'git-pull' <options> <repository> <refspec>...
  12
  13
  14 DESCRIPTION
  15 -----------
  16 Runs `git-fetch` with the given parameters, and calls `git-merge`
  17 to merge the retrieved head(s) into the current branch.
  18
  19 Note that you can use `.` (current directory) as the
  20 <repository> to pull from the local repository -- this is useful
  21 when merging local branches into the current branch.
  22
  23 OPTIONS
  24 -------
  25 include::pull-fetch-param.txt[]
  26
  27 -a, \--append::
  28         Append ref names and object names of fetched refs to the
  29         existing contents of `$GIT_DIR/FETCH_HEAD`.  Without this
  30         option old data in `$GIT_DIR/FETCH_HEAD` will be overwritten.
  31
  32 include::merge-pull-opts.txt[]
  33
  34
  35 MERGE STRATEGIES
  36 ----------------
  37
  38 resolve::
  39         This can only resolve two heads (i.e. the current branch
  40         and another branch you pulled from) using 3-way merge
  41         algorithm.  It tries to carefully detect criss-cross
  42         merge ambiguities and is considered generally safe and
  43         fast.  This is the default merge strategy when pulling
  44         one branch.
  45
  46 recursive::
  47         This can only resolve two heads using 3-way merge
  48         algorithm.  When there are more than one common
  49         ancestors that can be used for 3-way merge, it creates a
  50         merged tree of the common ancestores and uses that as
  51         the reference tree for the 3-way merge.  This has been
  52         reported to result in fewer merge conflicts without
  53         causing mis-merges by tests done on actual merge commits
  54         taken from Linux 2.6 kernel development history.
  55         Additionally this can detect and handle merges involving
  56         renames.
  57
  58 octopus::
  59         This resolves more than two-head case, but refuses to do
  60         complex merge that needs manual resolution.  It is
  61         primarily meant to be used for bundling topic branch
  62         heads together.  This is the default merge strategy when
  63         pulling more than one branch.
  64
  65 ours::
  66         This resolves any number of heads, but the result of the
  67         merge is always the current branch head.  It is meant to
  68         be used to supersede old development history of side
  69         branches.
  70
  71
  72 EXAMPLES
  73 --------
  74
  75 git pull, git pull origin::
  76         Fetch the default head from the repository you cloned
  77         from and merge it into your current branch.
  78
  79 git pull -s ours . obsolete::
  80         Merge local branch `obsolete` into the current branch,
  81         using `ours` merge strategy.
  82
  83 git pull . fixes enhancements::
  84         Bundle local branch `fixes` and `enhancements` on top of
  85         the current branch, making an Octopus merge.
  86
  87 git pull --no-commit . maint::
  88         Merge local branch `maint` into the current branch, but
  89         do not make a commit automatically.  This can be used
  90         when you want to include further changes to the merge,
  91         or want to write your own merge commit message.
  92 +
  93 You should refrain from abusing this option to sneak substantial
  94 changes into a merge commit.  Small fixups like bumping
  95 release/version name would be acceptable.
  96
  97 Command line pull of multiple branches from one repository::
  98 +
  99 ------------------------------------------------
 100 $ cat .git/remotes/origin
 101 URL: git://git.kernel.org/pub/scm/git/git.git
 102 Pull: master:origin
 103
 104 $ git checkout master
 105 $ git fetch origin master:origin +pu:pu maint:maint
 106 $ git pull . origin
 107 ------------------------------------------------
 108 +
 109 Here, a typical `$GIT_DIR/remotes/origin` file from a
 110 `git-clone` operation is used in combination with
 111 command line options to `git-fetch` to first update
 112 multiple branches of the local repository and then
 113 to merge the remote `origin` branch into the local
 114 `master` branch.  The local `pu` branch is updated
 115 even if it does not result in a fast forward update.
 116 Here, the pull can obtain its objects from the local
 117 repository using `.`, as the previous `git-fetch` is
 118 known to have already obtained and made available
 119 all the necessary objects.
 120
 121
 122 Pull of multiple branches from one repository using `$GIT_DIR/remotes` file::
 123 +
 124 ------------------------------------------------
 125 $ cat .git/remotes/origin
 126 URL: git://git.kernel.org/pub/scm/git/git.git
 127 Pull: master:origin
 128 Pull: +pu:pu
 129 Pull: maint:maint
 130
 131 $ git checkout master
 132 $ git pull origin
 133 ------------------------------------------------
 134 +
 135 Here, a typical `$GIT_DIR/remotes/origin` file from a
 136 `git-clone` operation has been hand-modified to include
 137 the branch-mapping of additional remote and local
 138 heads directly.  A single `git-pull` operation while
 139 in the `master` branch will fetch multiple heads and
 140 merge the remote `origin` head into the current,
 141 local `master` branch.
 142
 143
 144 SEE ALSO
 145 --------
 146 gitlink:git-fetch[1], gitlink:git-merge[1]
 147
 148
 149 Author
 150 ------
 151 Written by Linus Torvalds <torvalds@osdl.org>
 152 and Junio C Hamano <junkio@cox.net>
 153
 154 Documentation
 155 --------------
 156 Documentation by Jon Loeliger,
 157 David Greaves,
 158 Junio C Hamano and the git-list <git@vger.kernel.org>.
 159
 160 GIT
 161 ---
 162 Part of the gitlink:git[7] suite
 163