Comment 4 for bug 6700

There are a large number of Use Cases here I can imagine we want to support. We may not implement all of those immediately but I'd like to ensure we're agreed on an interface that is both easy-to-love and scalable. As I see it, we need the power to:

* compare pretty much any combination of working tree, branch revision, another working tree, anther branch revision
* optionally filter by a list of file and directory names.

Looking at SVN's diff command (http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.diff.html), it's usage is:

    svn diff [-r N[:M]] [TARGET[@REV]...]
    svn diff [-r N[:M]] --old OLD-TGT[@OLDREV] [--new NEW-TGT[@NEWREV]] [PATH...]
    svn diff OLD-URL[@OLDREV] NEW-URL[@NEWREV]

And here's the usage for git-diff (http://www.kernel.org/pub/software/scm/git/docs/git-diff.html):

    git-diff [<common diff options>] <commit>{0,2} [--] [<path>…]

I prefer the git approach of tree/branch URLs on the command line (as opposed to --old and --new + special cases) but suggest they go after the file list. Here's the proposed usage:

  bzr diff [FILE...] [FROM_LOCATION] [TO_LOCATION]

The full text of the proposed help including examples is attached.