Update "crosses branches"

[Stuart W. Marks]

Stephen Rasku wrote:
> I issued a "hg up -r tip" to get to the tip of my repository.  When I
> issue that command, I get the following error:
> 
>     abort: crosses branches (use 'hg merge' or 'hg update -C')
> 
> "hg status" confirms that there are no changed files.  Is it expected
> to use "hg update -C" even when there is nothing modified?  There is
> nothing in "hg help update" about using -C when there are no
> modifications.  Using the -C option resolved the issue but I am
> confused as to why it was necessary.
> 
> This is for Mercurial 1.2.1.

Yes, the need to supply the -C/--clean option in this case is confusing. The 
root cause is, I believe, that this option is overloaded to have two meanings: 
1) discard any pending changes, and 2) allow updating to another branch.

The situation is somewhat improved in 1.3.1 with the addition of the -c/--check 
option. This aborts the update if there uncommitted changes; it also allows 
updating to another branch. It's safer to use than -C/--clean because 
-c/--check will never discard any uncommitted changes.

So, the short answer is for you to upgrade to 1.3.1 and use -c/--check instead.

The non-short answer (which I hope will spark some discussion) involves the 
issue of why "update" will refuse to update to another branch even when there 
are no uncommitted changes. The precise behavior is more subtle than I had 
described above. When there are no uncommitted changes, update allows updating 
to *another* named branch, but not to another topological branch on the *same* 
named branch. In the latter case one must supply an option (either -C or -c) to 
allow the update to proceed. Not only is this very subtle, but it seems 
inconsistent as well.

I don't understand why there's any restriction about crossing branches at all, 
in the case where the working directory is clean. Why not just allow it and not 
require any options?

To be sure, -c/--check is an improvement over -C/--clean. However, it's still 
somewhat confusing because, like -C/--clean, it's also overloaded. 
Specifically, -c/--check means 1) abort the update if there are uncommitted 
changes, and 2) allow crossing to another topological branch of the same named 
branch.

The poor state of the "hg update" help text reflects this confusion, I think. 
In particular it doesn't explain at all the subtle restrictions on when branch 
crossing is allowed and that -c or -C override this restriction. I'm tempted to 
dive in an fix the help text, but I'd rather first simplify update by relaxing 
its restrictions. Not only will this reduce confusion, but it will also enable 
clearer help text to be written.

Can we allow update to cross to any branch (same or different name) when the 
working directory is clean?

s'marks