[PATCH V2] core.filemode may need manual action

["Torsten Bögershausen" <tboegi@web.de>]

core.filemode is set automatically when a repo is created.
But when a repo is exported via CIFS or cygwin is mixed with Git for Windows
or Eclipse core.filemode may better be set manually to false.
Update and improve the documentation

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Torsten Bögershausen <tboegi@web.de>
---

Thanks for careful reading.
Changes since V1:
- The '+' at an otherwise empty line generates an empty line
  in html, so s/^$/+/
- Changed msygit into Git for Windows
- Mention Eclipse
- Minor changes in the wording, remove one comma
- Remove the "The default is true, except "
  This line is maybe confusing.
  "The default is true" is not wrong as such, we have
  int trust_executable_bit = 1;
  But: these days most repos have core.filemode defined,
  so describing this default gives not much new information to the
  user. (please correct me if that is wrong)
  Especially the "except" is not really helpful, because
  the default is always true, and git.git will always probe.
  Any thoughts ?
  Now we mention the probing 2 times, I am not 100% happy with this,
  please see V2B

  Another thing is that both Git for Windows and Eclipse can not handle
  the filemode, and should silently ignore the flag, which is a different
  patch.


 Documentation/config.txt | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 04a1e2f..959dc11 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -204,12 +204,27 @@ advice.*::
 --
 
 core.fileMode::
-	If false, the executable bit differences between the index and
-	the working tree are ignored; useful on broken filesystems like FAT.
+	Tells Git if the executable bit of files in the working tree
+	is to be honored.
++
+	Some filesystems lose the executable bit when a file that is
+	marked as executable is checked out, or checks out an
+	non-executable file with executable bit on.  "git init" and
+	"git clone" probe the filesystem to see if it records
+	executable bit correctly when they create a new repository
+	and this variable is automatically set as necessary.
++
+	A repository, however, may be on a filesystem that handles
+	the filemode correctly, and this variable is set to 'true'
+	when created, but later may be made accessible from another
+	environment that loses the filemode (e.g. exporting ext4 via
+	CIFS mount, visiting a Cygwin created repository with
+	Git for Windows or Eclipse).
+	In such a case it may be necessary to set this variable to 'false'.
 	See linkgit:git-update-index[1].
 +
-The default is true, except linkgit:git-clone[1] or linkgit:git-init[1]
-will probe and set core.fileMode false if appropriate when the
+linkgit:git-clone[1] or linkgit:git-init[1]
+will probe and set core.fileMode to true or false when the
 repository is created.
 
 core.ignorecase::
-- 
2.1.0.rc2.210.g636bceb