Documentation/git-pull.txt - jrn/git - Git at Google

 git-pull(1)
 ===========

 NAME
 ----
 git-pull - Fetch from and integrate with another repository or a local branch


 SYNOPSIS
 --------
 [verse]
 'git pull' [<options>] [<repository> [<refspec>...]]


 DESCRIPTION
 -----------

 Incorporates changes from a remote repository into the current
 branch.  In its default mode, `git pull` is shorthand for
 `git fetch` followed by `git merge FETCH_HEAD`.

 More precisely, 'git pull' runs 'git fetch' with the given
 parameters and calls 'git merge' to merge the retrieved branch
 heads into the current branch.
 With `--rebase`, it runs 'git rebase' instead of 'git merge'.

 <repository> should be the name of a remote repository as
 passed to linkgit:git-fetch[1].  <refspec> can name an
 arbitrary remote ref (for example, the name of a tag) or even
 a collection of refs with corresponding remote-tracking branches
 (e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
 but usually it is the name of a branch in the remote repository.

 Default values for <repository> and <branch> are read from the
 "remote" and "merge" configuration for the current branch
 as set by linkgit:git-branch[1] `--track`.

 Assume the following history exists and the current branch is
 "`master`":

 ------------
 	  A---B---C master on origin
 	 /
     D---E---F---G master
 	^
 	origin/master in your repository
 ------------

 Then "`git pull`" will fetch and replay the changes from the remote
 `master` branch since it diverged from the local `master` (i.e., `E`)
 until its current commit (`C`) on top of `master` and record the
 result in a new commit along with the names of the two parent commits
 and a log message from the user describing the changes.

 ------------
 	  A---B---C origin/master
 	 /         \
     D---E---F---G---H master
 ------------

 See linkgit:git-merge[1] for details, including how conflicts
 are presented and handled.

 In Git 1.7.0 or later, to cancel a conflicting merge, use
 `git reset --merge`.  *Warning*: In older versions of Git, running 'git pull'
 with uncommitted changes is discouraged: while possible, it leaves you
 in a state that may be hard to back out of in the case of a conflict.

 If any of the remote changes overlap with local uncommitted changes,
 the merge will be automatically canceled and the work tree untouched.
 It is generally best to get any local changes in working order before
 pulling or stash them away with linkgit:git-stash[1].

 OPTIONS
 -------

 -q::
 --quiet::
 	This is passed to both underlying git-fetch to squelch reporting of
 	during transfer, and underlying git-merge to squelch output during
 	merging.

 -v::
 --verbose::
 	Pass --verbose to git-fetch and git-merge.

 --[no-]recurse-submodules[=yes|on-demand|no]::
 	This option controls if new commits of populated submodules should
 	be fetched, and if the working trees of active submodules should be
 	updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
 	linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
 If the update is done via merge, the submodule conflicts are resolved and checked out.

 Options related to merging
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

 :git-pull: 1

 include::merge-options.txt[]

 -r::
 --rebase[=false|true|merges|preserve|interactive]::
 	When true, rebase the current branch on top of the upstream
 	branch after fetching. If there is a remote-tracking branch
 	corresponding to the upstream branch and the upstream branch
 	was rebased since last fetched, the rebase uses that information
 	to avoid rebasing non-local changes.
 +
 When set to `merges`, rebase using `git rebase --rebase-merges` so that
 the local merge commits are included in the rebase (see
 linkgit:git-rebase[1] for details).
 +
 When set to `preserve` (deprecated in favor of `merges`), rebase with the
 `--preserve-merges` option passed to `git rebase` so that locally created
 merge commits will not be flattened.
 +
 When false, merge the current branch into the upstream branch.
 +
 When `interactive`, enable the interactive mode of rebase.
 +
 See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
 linkgit:git-config[1] if you want to make `git pull` always use
 `--rebase` instead of merging.
 +
 [NOTE]
 This is a potentially _dangerous_ mode of operation.
 It rewrites history, which does not bode well when you
 published that history already.  Do *not* use this option
 unless you have read linkgit:git-rebase[1] carefully.

 --no-rebase::
 	Override earlier --rebase.

 Options related to fetching
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

 include::fetch-options.txt[]

 include::pull-fetch-param.txt[]

 include::urls-remotes.txt[]

 include::merge-strategies.txt[]

 DEFAULT BEHAVIOUR
 -----------------

 Often people use `git pull` without giving any parameter.
 Traditionally, this has been equivalent to saying `git pull
 origin`.  However, when configuration `branch.<name>.remote` is
 present while on branch `<name>`, that value is used instead of
 `origin`.

 In order to determine what URL to use to fetch from, the value
 of the configuration `remote.<origin>.url` is consulted
 and if there is not any such variable, the value on the `URL:` line
 in `$GIT_DIR/remotes/<origin>` is used.

 In order to determine what remote branches to fetch (and
 optionally store in the remote-tracking branches) when the command is
 run without any refspec parameters on the command line, values
 of the configuration variable `remote.<origin>.fetch` are
 consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>`
 is consulted and its `Pull:` lines are used.
 In addition to the refspec formats described in the OPTIONS
 section, you can have a globbing refspec that looks like this:

 ------------
 refs/heads/*:refs/remotes/origin/*
 ------------

 A globbing refspec must have a non-empty RHS (i.e. must store
 what were fetched in remote-tracking branches), and its LHS and RHS
 must end with `/*`.  The above specifies that all remote
 branches are tracked using remote-tracking branches in
 `refs/remotes/origin/` hierarchy under the same name.

 The rule to determine which remote branch to merge after
 fetching is a bit involved, in order not to break backward
 compatibility.

 If explicit refspecs were given on the command
 line of `git pull`, they are all merged.

 When no refspec was given on the command line, then `git pull`
 uses the refspec from the configuration or
 `$GIT_DIR/remotes/<origin>`.  In such cases, the following
 rules apply:

 . If `branch.<name>.merge` configuration for the current
   branch `<name>` exists, that is the name of the branch at the
   remote site that is merged.

 . If the refspec is a globbing one, nothing is merged.

 . Otherwise the remote branch of the first refspec is merged.


 EXAMPLES
 --------

 * Update the remote-tracking branches for the repository
   you cloned from, then merge one of them into your
   current branch:
 +
 ------------------------------------------------
 $ git pull
 $ git pull origin
 ------------------------------------------------
 +
 Normally the branch merged in is the HEAD of the remote repository,
 but the choice is determined by the branch.<name>.remote and
 branch.<name>.merge options; see linkgit:git-config[1] for details.

 * Merge into the current branch the remote branch `next`:
 +
 ------------------------------------------------
 $ git pull origin next
 ------------------------------------------------
 +
 This leaves a copy of `next` temporarily in FETCH_HEAD, and
 updates the remote-tracking branch `origin/next`.
 The same can be done by invoking fetch and merge:
 +
 ------------------------------------------------
 $ git fetch origin
 $ git merge origin/next
 ------------------------------------------------


 If you tried a pull which resulted in complex conflicts and
 would want to start over, you can recover with 'git reset'.


 include::transfer-data-leaks.txt[]

 BUGS
 ----
 Using --recurse-submodules can only fetch new commits in already checked
 out submodules right now. When e.g. upstream added a new submodule in the
 just fetched commits of the superproject the submodule itself cannot be
 fetched, making it impossible to check out that submodule later without
 having to do a fetch again. This is expected to be fixed in a future Git
 version.

 SEE ALSO
 --------
 linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1]

 GIT
 ---
 Part of the linkgit:git[1] suite
	git-pull(1)
	===========

	NAME
	----
	git-pull - Fetch from and integrate with another repository or a local branch


	SYNOPSIS
	--------
	[verse]
	'git pull' [<options>] [<repository> [<refspec>...]]


	DESCRIPTION
	-----------

	Incorporates changes from a remote repository into the current
	branch. In its default mode, `git pull` is shorthand for
	`git fetch` followed by `git merge FETCH_HEAD`.

	More precisely, 'git pull' runs 'git fetch' with the given
	parameters and calls 'git merge' to merge the retrieved branch
	heads into the current branch.
	With `--rebase`, it runs 'git rebase' instead of 'git merge'.

	<repository> should be the name of a remote repository as
	passed to linkgit:git-fetch[1]. <refspec> can name an
	arbitrary remote ref (for example, the name of a tag) or even
	a collection of refs with corresponding remote-tracking branches
	(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
	but usually it is the name of a branch in the remote repository.

	Default values for <repository> and <branch> are read from the
	"remote" and "merge" configuration for the current branch
	as set by linkgit:git-branch[1] `--track`.

	Assume the following history exists and the current branch is
	"`master`":

	------------
	A---B---C master on origin
	/
	D---E---F---G master
	^
	origin/master in your repository
	------------

	Then "`git pull`" will fetch and replay the changes from the remote
	`master` branch since it diverged from the local `master` (i.e., `E`)
	until its current commit (`C`) on top of `master` and record the
	result in a new commit along with the names of the two parent commits
	and a log message from the user describing the changes.

	------------
	A---B---C origin/master
	/ \
	D---E---F---G---H master
	------------

	See linkgit:git-merge[1] for details, including how conflicts
	are presented and handled.

	In Git 1.7.0 or later, to cancel a conflicting merge, use
	`git reset --merge`. Warning: In older versions of Git, running 'git pull'
	with uncommitted changes is discouraged: while possible, it leaves you
	in a state that may be hard to back out of in the case of a conflict.

	If any of the remote changes overlap with local uncommitted changes,
	the merge will be automatically canceled and the work tree untouched.
	It is generally best to get any local changes in working order before
	pulling or stash them away with linkgit:git-stash[1].

	OPTIONS
	-------

	-q::
	--quiet::
	This is passed to both underlying git-fetch to squelch reporting of
	during transfer, and underlying git-merge to squelch output during
	merging.

	-v::
	--verbose::
	Pass --verbose to git-fetch and git-merge.

	--[no-]recurse-submodules[=yes\|on-demand\|no]::
	This option controls if new commits of populated submodules should
	be fetched, and if the working trees of active submodules should be
	updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
	linkgit:gitmodules[5]).
	+
	If the checkout is done via rebase, local submodule commits are rebased as well.
	+
	If the update is done via merge, the submodule conflicts are resolved and checked out.

	Options related to merging
	~~~~~~~~~~~~~~~~~~~~~~~~~~

	:git-pull: 1

	include::merge-options.txt[]

	-r::
	--rebase[=false\|true\|merges\|preserve\|interactive]::
	When true, rebase the current branch on top of the upstream
	branch after fetching. If there is a remote-tracking branch
	corresponding to the upstream branch and the upstream branch
	was rebased since last fetched, the rebase uses that information
	to avoid rebasing non-local changes.
	+
	When set to `merges`, rebase using `git rebase --rebase-merges` so that
	the local merge commits are included in the rebase (see
	linkgit:git-rebase[1] for details).
	+
	When set to `preserve` (deprecated in favor of `merges`), rebase with the
	`--preserve-merges` option passed to `git rebase` so that locally created
	merge commits will not be flattened.
	+
	When false, merge the current branch into the upstream branch.
	+
	When `interactive`, enable the interactive mode of rebase.
	+
	See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
	linkgit:git-config[1] if you want to make `git pull` always use
	`--rebase` instead of merging.
	+
	[NOTE]
	This is a potentially _dangerous_ mode of operation.
	It rewrites history, which does not bode well when you
	published that history already. Do not use this option
	unless you have read linkgit:git-rebase[1] carefully.

	--no-rebase::
	Override earlier --rebase.

	Options related to fetching
	~~~~~~~~~~~~~~~~~~~~~~~~~~~

	include::fetch-options.txt[]

	include::pull-fetch-param.txt[]

	include::urls-remotes.txt[]

	include::merge-strategies.txt[]

	DEFAULT BEHAVIOUR
	-----------------

	Often people use `git pull` without giving any parameter.
	Traditionally, this has been equivalent to saying `git pull
	origin`. However, when configuration `branch.<name>.remote` is
	present while on branch `<name>`, that value is used instead of
	`origin`.

	In order to determine what URL to use to fetch from, the value
	of the configuration `remote.<origin>.url` is consulted
	and if there is not any such variable, the value on the `URL:` line
	in `$GIT_DIR/remotes/<origin>` is used.

	In order to determine what remote branches to fetch (and
	optionally store in the remote-tracking branches) when the command is
	run without any refspec parameters on the command line, values
	of the configuration variable `remote.<origin>.fetch` are
	consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>`
	is consulted and its `Pull:` lines are used.
	In addition to the refspec formats described in the OPTIONS
	section, you can have a globbing refspec that looks like this:

	------------
	refs/heads/:refs/remotes/origin/
	------------

	A globbing refspec must have a non-empty RHS (i.e. must store
	what were fetched in remote-tracking branches), and its LHS and RHS
	must end with `/*`. The above specifies that all remote
	branches are tracked using remote-tracking branches in
	`refs/remotes/origin/` hierarchy under the same name.

	The rule to determine which remote branch to merge after
	fetching is a bit involved, in order not to break backward
	compatibility.

	If explicit refspecs were given on the command
	line of `git pull`, they are all merged.

	When no refspec was given on the command line, then `git pull`
	uses the refspec from the configuration or
	`$GIT_DIR/remotes/<origin>`. In such cases, the following
	rules apply:

	. If `branch.<name>.merge` configuration for the current
	branch `<name>` exists, that is the name of the branch at the
	remote site that is merged.

	. If the refspec is a globbing one, nothing is merged.

	. Otherwise the remote branch of the first refspec is merged.


	EXAMPLES
	--------

	* Update the remote-tracking branches for the repository
	you cloned from, then merge one of them into your
	current branch:
	+
	------------------------------------------------
	$ git pull
	$ git pull origin
	------------------------------------------------
	+
	Normally the branch merged in is the HEAD of the remote repository,
	but the choice is determined by the branch.<name>.remote and
	branch.<name>.merge options; see linkgit:git-config[1] for details.

	* Merge into the current branch the remote branch `next`:
	+
	------------------------------------------------
	$ git pull origin next
	------------------------------------------------
	+
	This leaves a copy of `next` temporarily in FETCH_HEAD, and
	updates the remote-tracking branch `origin/next`.
	The same can be done by invoking fetch and merge:
	+
	------------------------------------------------
	$ git fetch origin
	$ git merge origin/next
	------------------------------------------------


	If you tried a pull which resulted in complex conflicts and
	would want to start over, you can recover with 'git reset'.


	include::transfer-data-leaks.txt[]

	BUGS
	----
	Using --recurse-submodules can only fetch new commits in already checked
	out submodules right now. When e.g. upstream added a new submodule in the
	just fetched commits of the superproject the submodule itself cannot be
	fetched, making it impossible to check out that submodule later without
	having to do a fetch again. This is expected to be fixed in a future Git
	version.

	SEE ALSO
	--------
	linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1]

	GIT
	---
	Part of the linkgit:git[1] suite