Trouble merging upstream changes back into my branch

I'm running into conflicts while trying to merge upstream changes back into my branch and I'm not sure how to resolve them.

I created my own fork. I cloned it. I made changes to the branch on my fork, committed, and pushed. But then the main fork updated, and I tried to update my own fork by merging upstream in like so:

$ cd repo-name
$ git remote add upstream git://github.com/username/repo-name.git
$ git fetch upstream
$ git merge upstream/master

The merge says that there's some problem with a file and auto-merging doesn't work. It tells me to fix it myself and re-merge. So I actually went to the (upstream) repository on GitHub of the main fork and copied all the code of the new file into the file on my fork, and tried to merge again. Then, git gives me this error:

fatal: 'merge' is not possible because you have unmerged files. Please, fix them up in the work tree, and then use 'git add/rm ' as appropriate to mark resolution and make a commit, or use 'git commit -a'.

Is there some argument I'm leaving out? Am I doing something stupid? What does it mean by "unmerged files?" Isn't the whole point of merging to merge files? Do I have to commit my changes before I merge?

What you are seeing means that automatic merge could not resolve the conflicts in the files. You need to resolve these conflicts manually. Run git mergetool or git gui.

The "git merge" command tries to incorporate changes from another branch onto the present branch. If the merge is clean, meaning no conflicts, it will commit. Since your merge did have conflicts, it didn't commit. You need to resolve the conflict.

Pulling the copy from the upstream repo is one way to do that - by accepting the upstream repo's version. You can do that within git using "git checkout --theirs conflicting_file.txt"

Editing the file to get it into the shape you want is another way.

Once it's fixed, you need to add using "git add conflicting_file.txt" then commit. Then your working copy is clean and ready for more hacking. Good luck.

In Git there are cases merge refuses to even start in order to protect your local changes. This may happen in two cases:

• You have uncommitted changes in you repository that conflict with merge. The git will refuse to do a merge with the following message:

  error: Your local changes to the following files would be overwritten by merge:
          foo
  Please, commit your changes or stash them before you can merge.
  Aborting
  

  Then you have to either commit the changes first (git commit -a or git add + git commit), or stash them away with git stash save.

• You are in the middle of some unfinished merge-y operation. There was some conflict, for example

  Auto-merging foo
  CONFLICT (content): Merge conflict in foo
  Automatic merge failed; fix conflicts and then commit the result.
  

  and you have not finished resolving conflicts (by editing files and marking them as resolved with git add, or using some graphical merge tool via git mergetool) and didn't create a final merge commit with git commit -a, or aborted the merge with git reset --hard (NOTE: this will discard all you changes, and you will loose work done on resolving conflicts!!!).

  Or you have just run second git merge too fast, or used git merge instead of git commit to create a merge commit.

  error: 'merge' is not possible because you have unmerged files.
  hint: Fix them up in the work tree,
  hint: and then use 'git add/rm ' as
  hint: appropriate to mark resolution and make a commit,
  hint: or use 'git commit -a'.
  fatal: Exiting because of an unresolved conflict.
  

  Resolve conflicts as described e.g. in old Fun with completing a merge article by Junio C Hamano and finalize a merge with git commit, or discard a merge, or stash it away. Then if you meant to create this second merge, you can do it.

Sidenote: by default git-aware shell prompt shows if you are in the middle of merge, rebase or applying patches (git am operation). You can also configure it to show if the working directory is dirty (different from latest version, i.e. HEAD).