[PATCH 3 of 3 STABLE V2] doc: add explanation about Mercurial specific escaping for subpaths

FUJIWARA Katsunori foozy at lares.dti.ne.jp
Tue May 22 05:00:02 CDT 2012


At Mon, 21 May 2012 11:22:02 +0200,
Mads wrote:
> 
> On 21/05/12 10:22, FUJIWARA Katsunori wrote:
> > At Fri, 18 May 2012 15:20:35 -0500,
> > Matt Mackall wrote:
> >> On Wed, 2012-05-16 at 17:05 +0900, FUJIWARA Katsunori wrote:
> >>> # HG changeset patch
> >>> # User FUJIWARA Katsunori<foozy at lares.dti.ne.jp>
> >>> # Date 1337155350 -32400
> >>> # Branch stable
> >>> # Node ID 7cd7ea68a04d5f28d664f6183a3e07011b1a89a0
> >>> # Parent  c3eeae0a2e0ff4c0f493eb918f7458f2b12d93cb
> >>> doc: add explanation about Mercurial specific escaping for subpaths
> >>>
> >>> diff -r c3eeae0a2e0f -r 7cd7ea68a04d mercurial/help/config.txt
> >>> --- a/mercurial/help/config.txt	Wed May 16 17:02:30 2012 +0900
> >>> +++ b/mercurial/help/config.txt	Wed May 16 17:02:30 2012 +0900
> >>> @@ -1065,6 +1065,16 @@
> >>>
> >>>   rewrites ``http://server/foo-hg/`` into ``http://hg.server/foo/``.
> >>>
> >>> +.. note:: Even on Windows platforms, it is recommended to use ``/`` as
> >>> +   the path delimiter for local paths instead of ``\``, because the latter is
> >>> +   the special character for the regular expression.
> >> Actually, the reason is that '/' is portable across all the supported
> >> operating systems and '\' is not, and is thus our internal standard for
> >> file naming.
> >>
> >>> +   For convenience, recent Mercurial escapes backslashes in
> >>> +   ``replacement`` at first, and then treats backslashes followed by
> >>> +   digits as back references of the regular expression. So, you can not
> >>> +   specify "the path element starting with digits" with backslashes as
> >>> +   path delimiters in ``replacement``.
> >> Probably too much detail.
> > Thank you for your comments.
> >
> > There is no documentation about Mercurial specific escaping for
> > subpath configurations described in "For convenience, ...." paragraph
> > above, so I think it should be explained at least for warning.
> >
> > What about this ?
> >
> >    .. note:: Even on Windows platforms, it is recommended to use ``/``
> >       as the path delimiter for local paths instead of ``\``, because
> >       the former is portable across all the supported operating systems
> >       and the latter is not.
> 
> IMO it also matters that \ traditionally is used for other purposes - 
> and that shows up for example in subpath replacements.

OK, I'll add so.

> >       In addition to it, recent Mercurial escapes ``\`` in
> >       ``replacement`` in the special way for backward
> >       compatibility. This may cause unexpected behavior.
> 
> As we discussed in http://markmail.org/message/eelgmlqd7zks7nca this 
> "special way" has fundamental problems. It uses the wrong kind of 
> escaping and there is some replacements that it can't handle. The best 
> way to fix that bug would be to remove the incorrect escape handling 
> completely - even though that unfortunately not will be fully backward 
> compatible.
> 
> Anyway, I don't think it is a good idea to add a "there is a bug here - 
> we won't fix it and we can't describe how to work around it" section to 
> the documentation.

Yes, I also think this should be fixed.

But as you also described above (and in previous our discussion), such
fix will break backward compatibility.

So, I think that (1) explain the problem about using '\' in
'replacement' of subpath section to warn not to use it at first, and
then (2) fix it after some (major or minor) releases.

# BTW, for (1), should I add the code to show warning message when '\'
# is used in 'replacement' on win ?

But should I both fix this and omit the explanation about it at same
time ?

----------------------------------------------------------------------
[FUJIWARA Katsunori]                             foozy at lares.dti.ne.jp


More information about the Mercurial-devel mailing list