[PATCH STABLE] doc: add "filesystem" additional help topic about filesystem specific behaviors

FUJIWARA Katsunori foozy at lares.dti.ne.jp
Thu Apr 26 11:37:26 CDT 2012


# HG changeset patch
# User FUJIWARA Katsunori <foozy at lares.dti.ne.jp>
# Date 1335458119 -32400
# Branch stable
# Node ID 698ec5a7dacadfdf92ba9817e03a95ad85f98ff8
# Parent  e3c7ca15cde24f7e1ef5018fcfd902f4d6c95adc
doc: add "filesystem" additional help topic about filesystem specific behaviors

diff -r e3c7ca15cde2 -r 698ec5a7daca contrib/wix/help.wxs
--- a/contrib/wix/help.wxs	Mon Apr 23 00:38:22 2012 +0900
+++ b/contrib/wix/help.wxs	Fri Apr 27 01:35:19 2012 +0900
@@ -14,6 +14,7 @@
           <File Name="environment.txt" />
           <File Name="extensions.txt" />
           <File Name="filesets.txt" />
+          <File Name="filesystem.txt" />
           <File Name="glossary.txt" />
           <File Name="hgignore.txt" />
           <File Name="hgweb.txt" />
diff -r e3c7ca15cde2 -r 698ec5a7daca mercurial/help.py
--- a/mercurial/help.py	Mon Apr 23 00:38:22 2012 +0900
+++ b/mercurial/help.py	Fri Apr 27 01:35:19 2012 +0900
@@ -74,6 +74,8 @@
    (["hgignore", "ignore"], _("syntax for Mercurial ignore files"),
     loaddoc('hgignore')),
    (["phases"], _("Working with Phases"), loaddoc('phases')),
+   (["filesystem"], _("How Mercurial Works on Filesystem"),
+    loaddoc('filesystem')),
 ])
 
 # Map topics to lists of callable taking the current topic help and
diff -r e3c7ca15cde2 -r 698ec5a7daca mercurial/help/filesystem.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/filesystem.txt	Fri Apr 27 01:35:19 2012 +0900
@@ -0,0 +1,243 @@
+Mercurial records changes to files on the filesystems into a history,
+and sometimes its behavior depends on the capabilities of the filesystems
+containing its repository.
+
+This help explains what and how Mercurial records and works for
+tracked files on each filesystem.
+
+Management other than contents
+""""""""""""""""""""""""""""""
+
+Mercurial records additional information from filesystems beyond simply
+the file content.
+
+Symbolic link (symlink)
+.......................
+
+Please see 'Working with symlinks' for more detail.
+
+Executable status (exec bit)
+............................
+
+Mercurial records the status of the exec bit for each tracked file.
+
+On some filesystems where the exec bit capability itself is not
+available (FAT filesystem, for example), or some platform where exec
+bit capability of Mercurial is not supported (e.g.: Windows and Cygwin
+for recent version), it is ignored.
+
+Filename
+........
+
+Mercurial records filenames of each tracked files into history using the same
+encoding as used in the filesystem.
+
+Even on case-insensitive filesystems, letter cases of filenames
+are usually preserved.
+
+This may cause case-folding collision problems on case-insensitive
+filesystems.
+
+Please see 'Working on case-insensitive filesystems' also.
+
+Working with symlinks
+"""""""""""""""""""""
+
+Mercurial can record symlinks not as the content of the linked file, but
+as the filename of the link destination.
+
+Merging with symlinks
+.....................
+
+If you use a special tool capable of merging with symlinks
+as your merge tool for Mercurial,
+you can merge between symlinks or between a symlink
+and a normal file.
+
+Otherwise and by default, you will be prompted to choose which merge
+parent's file content
+should be kept in the merged revision.
+
+Please see :hg:`help merge-tools` for detail.
+
+Environments without symlink support
+....................................
+
+On some filesystems where symlink itself is not available (e.g. FAT
+filesystem), or platforms where Mercurial doesn't currently support symlinks
+(e.g.: Windows and Cygwin for recent version), Mercurial writes
+symlinks as plain text files
+containing the destination of the symlink when updating the working directory.
+
+Fix accidental changes
+######################
+
+When you accidentally modify files which were originally symlinks in
+such an environment, :hg:`status` may not show any status for them.
+
+In this case, Mercurial considers that such modified files as
+clean, so :hg:`revert` does not restore them:
+:hg:`update`, similarly, will not.
+
+You should delete them from your working directory first, and then use
+:hg:`revert` to make them clean: or :hg:`update` to make the working
+directory clean.
+
+Working with hardlinks
+""""""""""""""""""""""
+
+Hardlinks in metadata
+.....................
+
+Mercurial uses hardlinks for efficiency of storage consumption of
+repository metadata.
+
+Please see :hg:`help clone` for detail: see also :hg:`help relink`
+if relink extension is enabled.
+
+Hardlinks in working directories
+................................
+
+Mercurial doesn't track association between hardlink-ed files in
+working directories. It only tracks the file content in its history.
+
+However, :hg:`update` and :hg`revert` unlink files before
+writing content into target files, so hardlink-ed content is not
+modified.
+
+Working on case-insensitive filesystems
+"""""""""""""""""""""""""""""""""""""""
+
+If you work on case-insensitive filesystems (e.g.: FAT filesystem,
+traditional NTFS on Windows, HFS+ on Mac OS, and so on), you should
+be aware of the following constraints and how to work with them.
+
+Warning for case-folding collision
+..................................
+
+You may see warning for case-folding collision during :hg:`add`::
+
+    $ hg add a.txt
+    $ hg add A.TXT
+    warning: possible case-folding collision for A.TXT
+
+In this case, collision occurs in files which you want to add, or
+between them and ones already existing in the 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 work on
+case-insensitive filesystems.
+
+You can make it an error by setting configuration
+``ui.portablefilenames`` to ``abort``.
+
+.. note::
+   See also ``portablefilenames`` in ``ui`` section of :hg:`help
+   config` for detail
+   
+Abort for case-folding collision
+................................
+
+Abort updating to another version
+#################################
+
+:hg:`update` will abort because of case-folding collisions, if target
+revision has files colliding each other::
+
+    $ hg update collidingrev
+    abort: case-folding collision between a.txt and A.TXT
+
+You can't update to such revisions on case-insensitive filesystems.
+
+.. note::
+   If you strongly want to (or have to) browse or repair such
+   revisions on case-insensitive filesystems, please see 'Updating
+   manually' section.
+
+It's possible for an update to abort, even though the target
+revision has no files with case collisions if files in the target
+revision and working directory are considered as a cause of
+case-folding collision in linear update merging.
+
+If you don't want to do linear update merging, please see 'Updating
+with --check or --clean'.
+
+Abort merging with another revision
+###################################
+
+:hg:`merge` may abort because of case-folding collisions::
+
+    $ hg merge
+    abort: case-folding collision between a.txt and A.TXT
+
+If you can :hg:`update --clean` to each merge target revisions, then files
+in the merging revisions are colliding with each other.
+
+To enable a merge, you will have to first rename one or the other file.
+
+Please see 'Renaming colliding files' section in this case.
+
+Case determination process in Mercurial
+.......................................
+
+On case-insensitive filesystems, Mercurial decides what case to use in
+the following order:
+
+  - the case recognized in Mercurial, if a file is already tracked.
+    you can see this in :hg:`status -amrdc` output.
+  - or the case used in the filesystem, if the file exists.
+    you can see this in :hg:`status -u` output.
+  - or the case given on the command line
+
+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 with case collisions.
+
+Renaming colliding files
+########################
+
+On case-insensitive filesystems, updating to revisions which have
+files with case collisions will abort, even with
+``--check`` or ``--clean``.
+
+To repair such revisions, you should give new names to one or both of
+the colliding files on a case-sensitive filesystem, and commit them to
+create new collision safe revision.
+
+.. note::
+   If you want to (or need to) browse or repair such
+   revisions on case-insensitive filesystems, 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 filesystems::
+
+    $ hg rename a.txt tmp
+    $ hg rename tmp A.TXT
+
+Updating manually
+#################
+
+If you want to (or need to) update working directory by the
+revision causing case-folding collision on case-insensitive
+filesystems, to rename colliding files or browsing contents at such
+revision for example, please see the Wiki page below::
+
+    http://mercurial.selenic.com/wiki/ManualCheckout
+
+This is NOT recommended for non expert Mercurial users.
diff -r e3c7ca15cde2 -r 698ec5a7daca tests/test-globalopts.t
--- a/tests/test-globalopts.t	Mon Apr 23 00:38:22 2012 +0900
+++ b/tests/test-globalopts.t	Fri Apr 27 01:35:19 2012 +0900
@@ -341,6 +341,7 @@
    environment   Environment Variables
    extensions    Using additional features
    filesets      Specifying File Sets
+   filesystem    How Mercurial Works on Filesystem
    glossary      Glossary
    hgignore      syntax for Mercurial ignore files
    hgweb         Configuring hgweb
@@ -425,6 +426,7 @@
    environment   Environment Variables
    extensions    Using additional features
    filesets      Specifying File Sets
+   filesystem    How Mercurial Works on Filesystem
    glossary      Glossary
    hgignore      syntax for Mercurial ignore files
    hgweb         Configuring hgweb
diff -r e3c7ca15cde2 -r 698ec5a7daca tests/test-help.t
--- a/tests/test-help.t	Mon Apr 23 00:38:22 2012 +0900
+++ b/tests/test-help.t	Fri Apr 27 01:35:19 2012 +0900
@@ -113,6 +113,7 @@
    environment   Environment Variables
    extensions    Using additional features
    filesets      Specifying File Sets
+   filesystem    How Mercurial Works on Filesystem
    glossary      Glossary
    hgignore      syntax for Mercurial ignore files
    hgweb         Configuring hgweb
@@ -191,6 +192,7 @@
    environment   Environment Variables
    extensions    Using additional features
    filesets      Specifying File Sets
+   filesystem    How Mercurial Works on Filesystem
    glossary      Glossary
    hgignore      syntax for Mercurial ignore files
    hgweb         Configuring hgweb
@@ -687,6 +689,7 @@
    environment   Environment Variables
    extensions    Using additional features
    filesets      Specifying File Sets
+   filesystem    How Mercurial Works on Filesystem
    glossary      Glossary
    hgignore      syntax for Mercurial ignore files
    hgweb         Configuring hgweb


More information about the Mercurial-devel mailing list