hg diff in the presence of subrepositories

[paul_nathan at selinc.com]

All,

I am working to deploy Mercurial in my company using subrepositories to 
manage our modules,
and I am providing support for developers.

Our repositories are structured along the lines recommended by mpm[1].

toplevel/ 
    ./module
    ./module
   ./productcode
   ./otherproductcode




One of the frequently asked questions I receive goes like this:

   Asker:

"""
I am trying to merge my top-level repository and I get this message:

~/dev/toplevel/$ hg merge other_branch
abort: outstanding uncommitted changes in subrepository 'MySubrepo'

~/dev/toplevel/$ cd MySubrepo

~/dev/toplevel/MySubrepo/$ hg sum 
parent: <blah>
<message>
branch: <blah>
commit: (clean)
update: (current)

~/dev/toplevel/MySubrepo/$ hg diff
~/dev/toplevel/MySubrepo/$ hg status


What's going on here?
"""

   Me:

"""
Check hg sum at root level
"""

   Asker:

"""
~/dev/toplevel/$ hg sum 
parent: <blah>
<message>
branch: <blah>
commit: 1 subreo
update: (current)

~/dev/toplevel/$ hg diff
~/dev/toplevel/$ hg st
~/dev/toplevel/$
"""

  Me

"""
You need to commit at the top level before merging, the subrepository 
state has changed under you.
"""

And the conversation continues as I explain the operation of the 
.hgsubstate file and how it records the state of the subrepos, but only on 
commit. 


The problem is: 

Notice that there is an inconsistency of operation here: hg diff is not 
telling the user that there really is a difference in the world of the top 
repository. Nor is hg status.
Yet, the connotation and denotation of the words say that they tell you 
the status and the difference. But they return that there is _no_ 
difference. 

While this may make sense from an implementation standpoint(and it does, 
if I think like an implementer),  I have received this question from 
multiple people who are 
experienced, skilled and qualified software engineers who have used other 
version control systems (ClearCase, SVN, git). 

>From my perspective as a support person for hg in my company, this is 
essentially a bug in the user experience and user interface. 

If there are subtle tricks I have not yet uncovered to make this plain to 
the user I support,  I would like to hear them.


[1] http://selenic.com/pipermail/mercurial-devel/2011-April/030128.html

- - -
Regards,
Paul Nathan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mercurial-scm.org/pipermail/mercurial/attachments/20110610/27bef750/attachment.html>