[PATCH 1 of 1] doc: add "icasefs" additional help topic for case insensitive filesystem
Matt Mackall
mpm at selenic.com
Mon Apr 16 13:19:03 CDT 2012
On Mon, 2012-04-16 at 23:02 +0900, FUJIWARA Katsunori wrote:
> # HG changeset patch
> # User FUJIWARA Katsunori <foozy at lares.dti.ne.jp>
> # Date 1334584599 -32400
> # Node ID 4e738ea05ee07701fdc90afcc641753fc5076eac
> # Parent 9b26d541e972428a21d44837650932b2f2f5aeb0
> doc: add "icasefs" additional help topic for case insensitive filesystem
I think we probably want a whole 'filesystem' topic instead, mentioning
symlinks, exec bits, and hardlinks. As this is a doc change, it can wait
until after the freeze.
This probably also wants to mention Mercurial's internal case precedence
rules:
- case in dirstate
- case on filesystem
- case on command line
Lots of missing "a"s and "the"s in this text. Perhaps we can find a
native English speaker who can copy-edit this a bit.
> diff -r 9b26d541e972 -r 4e738ea05ee0 contrib/wix/help.wxs
> --- a/contrib/wix/help.wxs Sat Apr 14 01:39:35 2012 -0500
> +++ b/contrib/wix/help.wxs Mon Apr 16 22:56:39 2012 +0900
> @@ -17,6 +17,7 @@
> <File Name="glossary.txt" />
> <File Name="hgignore.txt" />
> <File Name="hgweb.txt" />
> + <File Name="icasefs.txt" />
> <File Name="merge-tools.txt" />
> <File Name="multirevs.txt" />
> <File Name="patterns.txt" />
> diff -r 9b26d541e972 -r 4e738ea05ee0 mercurial/help.py
> --- a/mercurial/help.py Sat Apr 14 01:39:35 2012 -0500
> +++ b/mercurial/help.py Mon Apr 16 22:56:39 2012 +0900
> @@ -74,6 +74,8 @@
> (["hgignore", "ignore"], _("syntax for Mercurial ignore files"),
> loaddoc('hgignore')),
> (["phases"], _("Working with Phases"), loaddoc('phases')),
> + (["icasefs"], _("Working on case insensitive filesystm"),
> + loaddoc('icasefs')),
> ])
>
> # Map topics to lists of callable taking the current topic help and
> diff -r 9b26d541e972 -r 4e738ea05ee0 mercurial/help/icasefs.txt
> --- /dev/null Thu Jan 01 00:00:00 1970 +0000
> +++ b/mercurial/help/icasefs.txt Mon Apr 16 22:56:39 2012 +0900
> @@ -0,0 +1,141 @@
> +If you work on case insensitive filesystem (e.g.: NTFS on Windows,
> +HFS+ on Mac OS, and so on), you should know some know-how or
> +workaround on it.
> +
> +Warning for case-folding collision
> +----------------------------------
> +
> +You may see warning for case-folding collision at :hg:`add`.
> +In this case, collision occurs in files which you want to add, or
> +between them and ones already existing in parent revision.
> +
> +It is just warning, so specified files are added. But you must not add
> +such files, if you want to cooperate with members who (should) work on
> +case insensitive filesystem.
> +
> +.. note::
> + Please also see ``portablefilenames`` in ``ui`` section of :hg:`help
> + config` for detail
> +
> +Abort for case-folding collision
> +--------------------------------
> +
> +Abort updating to another version
> +"""""""""""""""""""""""""""""""""
> +
> +:hg:`update` is aborted for case-folding collision, if target
> +revision has files colliding each other.
> +
> +.. note::
> + If you want(or have) to browse or repair such revisions on case
> + insensitive filesystem, please see ``Updating manually`` section.
> +
> +Perhaps, your updating may be also aborted, even though the target
> +revision has no files colliding each other.
> +
> +In this case, :hg:`update` is aborted, because files in target
> +revision and working directory are considered as a cause of
> +case-folding collision in linear update merge, even though you don't
> +want to do linear update merging.
> +
> +Please see ``Updating with --check or --clean`` section in this case.
> +
> +Abort merging with another revision
> +"""""""""""""""""""""""""""""""""""
> +
> +:hg:`merge` may be aborted for case-folding collision.
> +
> +If you can ``update --clean`` to each target revisions, files in each
> +revisions should collide each other.
> +
> +Only if one of files colliding each other is renamed from the other,
> +Mercurial allows merging them into one of them: merging is not aborted
> +in this case.
> +
> +Otherwise, you should rename one of them or both to avoid case-folding
> +collision before merging.
> +
> +Please see ``Renaming colliding files`` section in this case.
> +
> +
> +Workaround
> +----------
> +
> +Updating with --check or --clean
> +""""""""""""""""""""""""""""""""
> +
> +Please use ``--check`` or ``--clean`` options to update working
> +directory simply.
> +
> +These options avoid collision check between target revision and
> +current working context, so you can update to specified revision, if
> +it has no files colliding each other.
> +
> +Renaming colliding files
> +""""""""""""""""""""""""
> +
> +On case insensitive filesystem, updating to revisions which have files
> +colliding each other is aborted in normal way, even with ``--check``
> +or ``--clean``.
> +
> +To repair such revisions, you should rename colliding files to another
> +on case sensitive filesystem, and commit them to create new collision
> +safe revision.
> +
> +.. note::
> + If you want(or have) to browse or repair such revisions on case
> + insensitive filesystem, please see ``Updating manually`` section.
> +
> +If :hg:`merge` is aborted, but :hg:`update --check` to each
> +revisions successes, collision occurs between revision to be merged.
> +
> +In this case, files in one of them or both should be renamed to avoid
> +collision before merging.
> +
> +With recent Mercurial, you can change case of filename safely in steps
> +below, even on case insensitive filesystem::
> +
> + $ hg rename a tmp
> + $ hg rename tmp A
> +
> +Updating manually
> +"""""""""""""""""
> +
> +You can update working directory to the revision which has files
> +colliding each other by bypassing consistency check of Mercurial.
> +
> +If you want to clone the repository which has such revisions, clone
> +with ``-U`` to avoid the initial checkout::
> +
> + $ hg clone -U REPOURL
> +
> +Or, if such revisions already exist in your repository, update working
> +directory by ``null`` revision at first::
> +
> + $ hg update null
> +
> +Next, use :hg:`revert` to retrieve all the files except the colliding
> +files from a `TARGET` revision::
> +
> + $ hg revert -a -r TARGET -X BADFILEPAT
> +
> +``BADFILEPAT`` is used to avoid retrieve colliding files, so two ore
> +more patterns may be required, if there are many collisions.
> +
> +Next, set the parent of the working copy to ``TARGET`` manually::
> +
> + $ hg debugrebuildstate -r TARGET
> +
> +Now, Mercurial should be in a state where the ``TARGET`` revisions is
> +checked out except the colliding files.
> +
> +For example, it is assumed that two files named as ``badfile`` and
> +``BADFILE`` exist in ``TARGET`` revision, and you want to rename
> +``BADFILE`` to ``ANOTHERFILE`` to avoid collision::
> +
> + $ hg cat -r TARGET -o ANOTHERFILE
> + $ hg rename --after BADFILE ANOTHERFILE
> +
> +Then, you can create the collision safe revision by committing above
> +renaming.
> diff -r 9b26d541e972 -r 4e738ea05ee0 tests/test-globalopts.t
> --- a/tests/test-globalopts.t Sat Apr 14 01:39:35 2012 -0500
> +++ b/tests/test-globalopts.t Mon Apr 16 22:56:39 2012 +0900
> @@ -344,6 +344,7 @@
> glossary Glossary
> hgignore syntax for Mercurial ignore files
> hgweb Configuring hgweb
> + icasefs Working on case insensitive filesystm
> merge-tools Merge Tools
> multirevs Specifying Multiple Revisions
> patterns File Name Patterns
> @@ -428,6 +429,7 @@
> glossary Glossary
> hgignore syntax for Mercurial ignore files
> hgweb Configuring hgweb
> + icasefs Working on case insensitive filesystm
> merge-tools Merge Tools
> multirevs Specifying Multiple Revisions
> patterns File Name Patterns
> diff -r 9b26d541e972 -r 4e738ea05ee0 tests/test-help.t
> --- a/tests/test-help.t Sat Apr 14 01:39:35 2012 -0500
> +++ b/tests/test-help.t Mon Apr 16 22:56:39 2012 +0900
> @@ -116,6 +116,7 @@
> glossary Glossary
> hgignore syntax for Mercurial ignore files
> hgweb Configuring hgweb
> + icasefs Working on case insensitive filesystm
> merge-tools Merge Tools
> multirevs Specifying Multiple Revisions
> patterns File Name Patterns
> @@ -194,6 +195,7 @@
> glossary Glossary
> hgignore syntax for Mercurial ignore files
> hgweb Configuring hgweb
> + icasefs Working on case insensitive filesystm
> merge-tools Merge Tools
> multirevs Specifying Multiple Revisions
> patterns File Name Patterns
> @@ -690,6 +692,7 @@
> glossary Glossary
> hgignore syntax for Mercurial ignore files
> hgweb Configuring hgweb
> + icasefs Working on case insensitive filesystm
> merge-tools Merge Tools
> multirevs Specifying Multiple Revisions
> patterns File Name Patterns
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at selenic.com
> http://selenic.com/mailman/listinfo/mercurial-devel
--
Mathematics is the supreme nostalgia of our time.
More information about the Mercurial-devel
mailing list