Do not run git-pull blindly

Note: I'm aware that git-pull has a well-defined use. This is mainly aimed at people who blindly run git pull when a push fails because of non-fast-forward updates. If you invoke pull with arguments, this article isn't for you. If you know that pull does a merge, this article probably isn't for you either.

Many newcomers to git use git-pull if a push fails. This appears to be compounded by two sources of bad advice:

SVN-to-Git transition guides such as this one recommend git pull as the equivalent of svn update. Unfortunately this is only correct in some border cases.
The rather unfortunate naming scheme insinuates that git-pull is the opposite of git-push. It is not.

Further note: many of the statements below would have to be qualified by the statement "unless you know exactly what you are doing". I won't repeat that every time; if you know exactly what you are doing, you don't need my help.

So what is git-pull?

There's an easy rule:

pull = fetch + merge

Once you have that memorised, everything else follows from the usual guidelines and warnings for merges:

Do not merge with any uncommitted changes in your tree.
Do not merge just to synchronise with upstream. (The gitworkflows manpage has some more information about this.)
Never merge rewritten history with pre-rewrite history. The result will never be what you want.

Note how the first point already means you must not use git pull as a substitute for svn update if you have any work pending "svn-style" in the worktree.

The second rule means that on branches you actually work on, you shouldn't need to pull at all (once at most if there are merge conflicts you want to sort out first).

I have uncommitted changes and want to pull!

You should probably rethink your workflow. Little topic branches work much better in the git model, see gitworkflows. If you correctly adapted your workflow to topic branches, you will note that you almost never have uncommitted changes lying around, let alone during integration rounds when you actually have to merge. Hence, you will never run into this problem.

In the rare case where you have to interrupt your work for a quick fix-test-merge round, just save the current work as a temporary commit with

git add -u
git commit -m WIP

or similar. You can then later use git reset HEAD^ to unwind the temporary commit. Also see git-stash for yet another solution.

Why is this so complicated?

Ok, ok, there is an easy and immediate band-aid:

git stash
git pull
git stash pop

Now please go and read gitworkflows.

And what about my failed push?

Failed pushes fall into one of several categories:

Upstream has changes that you don't have yet. Do not force the push. Depending on your exact workflow, a pull may be the correct choice here.
You rewrote history. Do not pull. Double check if upstream has any changes that you don't have yet (see the next point) and then force the push.
Both of the above. You're in serious trouble.

What do you mean, I'm in serious trouble?

If you want to push rewritten history to a branch where others have in the meantime published work that you didn't have at the time of rewriting, first note: You ignored all the warnings against rewriting history that is published, let alone in a repository where others work too. You failed to send notice to the other developers that you were going to rewrite. Promise to be more careful next time.

You will unfortunately have to redo either the rewriting or rebuild the changes on top of your rewritten commits:

Rebuilding the remote changes is exactly the process described in the "Recovering From Upstream Rebase" section in the rebase manpage, except that the roles are somewhat swapped: the remote changes in our discussion are the downstream in the manpage instructions.
Redoing the rewriting is applicable if you used a deterministic filter-branch operation, such as an index-filter to remove files. In such cases, it is enough to repeat the filter-branch operation so that histories converge again, and then merge.
Finally, you can of course choose to not do the rewriting. For example, if you rewrote by discarding a commit via git reset --hard HEAD^, it would be much better to undo the reset and revert instead.

In either case, you will rewrite history again, so this time around please tell your co-developers that you do so they can adjust accordingly. Give them the link to the "Recovering From Upstream Rebase" section in the rebase manpage while you are at it.

You lost me.

I'm terribly sorry. Please head to #git on irc.freenode.net, describe in what situation you are (what commands you ran, git-status output, etc.) and ask for help.

Note that

git log --graph --oneline --decorate --all

gives a pastebin-compatible overview over your history, which is very useful when trying to get help. You may want to use more specific branch heads if you have a lot of it.

If you managed to solve your problem, consider sending me an email so I can improve this page. (I am known as charon on IRC, but frequently not connected to the proxy.)