Differences between "git pull" commands when pulling from origin?

git pull is a convenience command, which is doing different things at the same time. Basically it is just a combination of git fetch, which connects to the remote repository and fetches new commits, and git merge (or git rebase) which incorporates the new commits into your local branch. Because of the two different commands involved the meaning of git pull is not always obvious.

You can configure an upstream for a local branch. After a fresh clone you will have a local branch "master", a remote "origin" and your master branch has "origin/master" as upstream. I assume this setup below. (You can see your upstream configuration with git branch -vv or by looking at .git/config.)

Now for your questions:

  1. git pull= git fetch origin + git merge origin/master (or whatever your upstream is)
  2. git pull origin = git pull (as long as origin is your upstream remote)
  3. git pull origin master = git fetch origin master+git merge FETCH_HEAD
  4. git pull origin/master : invalid unless you have a remote called "origin/master"
  5. git pull origin HEAD:master : Tries to directly reset you local master to whatever HEAD points to on origin. (Don't do this.)

A pull is basically a fetch (which gets some commits and associated objects from a remote repository into yours) and then an operation which "applies" these into your working copy. The second stage is, by default, done using a merge but you can set the pull.rebase variable to true and then it will rebase instead.

There are two questions that pop up with the pull command. The first is, what exactly gets fetched? And the second is, how does it apply these changes to my working copy? Let's start with the first. The full form of the command is

git pull [options] [repository] [<refspec>...]

The options are flags that control behaviour (e.g. --rebase to make pull work as a fetch + rebase even if pull.rebase is false).

repository is the name (or URL) of the remote to fetch from.

refspecs are a succinct way of specifying which references on the remote you want to fetch and where do you want to put them in your current working copy.

Let's take the most explicit form first.

 git pull origin branch1:branch2

This basically says, pull the changes in the reference branch1 on the remote called origin and then merge (or rebase) them into the local branch branch2. If I, for example, say git pull origin master:dev, I will get a local branch called dev which will point to the same commit as master. The details of how to specify refspecs are here. You can use a * to indicate multiple refspecs. For example, git pull origin refs/heads/*:refs/heads/* will pull all the branches (stored under heads) into the local repository and merge them into local branches with the same names.

Now, let's remove arguments one by one to discuss how the default work. First, we can remove the destination from our refspec and simply say git pull origin branch1. This will first fetch the remote branch branch1 into your local repository. It will be available as a temporary reference called FETCH_HEAD. After that, it will run git merge FETCH_HEAD which will merge this branch into your current active branch (i.e. HEAD). This is often done when you're in a local branch and want to fetch changes from a remote into that branch.

Now, let's drop the branch1 completely and just say git pull origin. Now, git knows where to fetch from (origin) but doesn't know what to fetch. It has some defaults for this. The most scenario is when your config file has a branch.<name>.merge option (this is an entry called merge inside a section like [branch "master"]). If so, it will use the refspecs there for the operation.

If we drop the origin completely and simply say git pull, it will check the config to see if there is a branch.<name>.remote which specifies which remote to pull from. That along with the above tells you what to pull.

Your points #4 and #5 are not normal use cases. The first makes sense if you have a remote called origin/master which is unlikely. origin/master is usually a local reference that tracks the master branch on the remote origin. The second will try to fetch changes on HEAD on the remote (the default branch which is usually master) and then merge those into your local master. While this might be something you want to do on a regular basis, the command is quite unconventional and not something I've seen used often.

I've skipped a few details but these should be enough to keep you safe and comfortable in your daily work. For all the gory details, you can check out the manual page for git pull.

Tags:

Git