Git Rebase Issue

[Pierre-Luc Loyer <Pierre-Luc.Loyer@bhvr.com>]

Hi,

I've encountered a situation using rebase for which I don't understand the results, even after reading the documentation.
I'm currently working in my feature branch and then I want to squash commits, thus I use interactive rebase. After successfully completing the rebase, I end up in a detached HEAD state, rather than back on my branch, which is confusing. The command that is causing me to be in detached HEAD mode is: git rebase -i HEAD~2 HEAD
From the documentation, I read that my second parameter (HEAD) is the <branch> parameter:

   git rebase [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]

   [<upstream>] [<branch>]

   If <branch> is specified, git rebase will perform an automatic git checkout <branch> before doing anything else. Otherwise it remains on the current branch.
<branch> Working branch; defaults to HEAD.

   Upon completion, <branch> will be the current branch.

Here is a full example than can be used to easily repro the issue. Go to an empty folder.
git init
git echo text > file.txt
git add .
git commit -m "Add file.txt"
git echo text2 > file.txt
git commit -am "Modify file.txt"
git echo text3 > file.txt
git commit -am "Remodify file.txt"

Now the interesting part:
$ git rebase -i HEAD~2 HEAD
[detached HEAD 9178b93] Modify file
1 file changed, 1 insertion(+), 1 deletion(-)
Successfully rebased and updated detached HEAD. 

From the documentation it says that <branch> (which is HEAD) will be checked out before doing anything and that upon completion, <branch> will be the current branch. However, this doesn't seem to happen. In fact, it seems more like the following is happening during the rebase:
1) detach HEAD
2) rebase
3) reattach to <branch>

If <branch> is HEAD, then is does nothing and remains detached.
I find this behavior confusing since I would expect it to return to whatever HEAD was pointing to at the start of the command, such as my branch. Also, the documentation says that the <branch> parameter defaults to HEAD, so passing 'HEAD' explicitly should result in the same behavior as not passing it:
<branch> Working branch; defaults to HEAD.

Pierre-Luc Loyer