Skip to content

git-pull.adoc

Latest commit

 

History

History
242 lines (192 loc) · 7.7 KB

git-pull.adoc

File metadata and controls

242 lines (192 loc) · 7.7 KB
Raw

git-pull(1)

NAME

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

SYNOPSIS

git pull [<options>] [<repository> [<refspec>…​]]

DESCRIPTION

Integrate changes from a remote repository into the current branch.

First, git pull runs git fetch with the same arguments (excluding merge options) to fetch remote branch(es). Then it decides which remote branch to integrate: if you run git pull with no arguments this defaults to the upstream for the current branch. Then it integrates that branch into the current branch.

There are 4 main options for integrating the remote branch:

  1. git pull --ff-only will only do "fast-forward" updates: it fails if your local branch has diverged from the remote branch. This is the default.

  2. git pull --rebase runs git rebase

  3. git pull --no-rebase runs git merge.

  4. git pull --squash runs git merge --squash

You can also set the configuration options pull.rebase, pull.squash, or pull.ff with your preferred behaviour.

If there’s a merge conflict during the merge or rebase that you don’t want to handle, you can safely abort it with git merge --abort or git --rebase abort.

OPTIONS

<repository>

The "remote" repository to pull from. This can be either a URL (see the section GIT URLS below) or the name of a remote (see the section REMOTES below).

Defaults to the configured upstream for the current branch, or origin. See UPSTREAM BRANCHES below for more on how to configure upstreams.

<refspec>

Which branch or other reference(s) to fetch and integrate into the current branch, for example main in git pull origin main. Defaults to the configured upstream for the current branch.

This can be a branch, tag, or other collection of reference(s). See <refspec> below under "Options related to fetching" for the full syntax, and DEFAULT BEHAVIOUR below for how git pull uses this argument to determine which remote branch to integrate.

-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.

--recurse-submodules[=(yes|on-demand|no)]
--no-recurse-submodules

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

-r
--rebase[=(false|true|merges|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 false, merge the upstream branch into the current 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

This is shorthand for --rebase=false.

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:

  1. 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.

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

  3. 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.

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