docs: explain how to deal with files that are always modified

Users frequently have problems where two filenames differ only in case,
causing one of those files to show up consistently as being modified.
Let's add a FAQ entry that explains how to deal with that.

In addition, let's explain another common case where files are
consistently modified, which is when files using a smudge or clean
filter have not been run through that filter.  Explain the way to fix
this as well.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 176b097cf7c14b24445de621c657b31a865792a0..afdaeab8503c30e24119d4b10544ba86d201a96b 100644 (file)
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -363,6 +363,39 @@ information about how to configure files as text or binary.
 You can also control this behavior with the `core.whitespace` setting if you
 don't wish to remove the carriage returns from your line endings.
 
+[[always-modified-files-case]]
+Why do I have a file that's always modified?::
+       Internally, Git always stores file names as sequences of bytes and doesn't
+       perform any encoding or case folding.  However, Windows and macOS by default
+       both perform case folding on file names.  As a result, it's possible to end up
+       with multiple files or directories whose names differ only in case.  Git can
+       handle this just fine, but the file system can store only one of these files,
+       so when Git reads the other file to see its contents, it looks modified.
++
+It's best to remove one of the files such that you only have one file.  You can
+do this with commands like the following (assuming two files `AFile.txt` and
+`afile.txt`) on an otherwise clean working tree:
++
+----
+$ git rm --cached AFile.txt
+$ git commit -m 'Remove files conflicting in case'
+$ git checkout .
+----
++
+This avoids touching the disk, but removes the additional file.  Your project
+may prefer to adopt a naming convention, such as all-lowercase names, to avoid
+this problem from occurring again; such a convention can be checked using a
+`pre-receive` hook or as part of a continuous integration (CI) system.
++
+It is also possible for perpetually modified files to occur on any platform if a
+smudge or clean filter is in use on your system but a file was previously
+committed without running the smudge or clean filter.  To fix this, run the
+following on an otherwise clean working tree:
++
+----
+$ git add --renormalize .
+----
+
 [[recommended-storage-settings]]
 What's the recommended way to store files in Git?::
        While Git can store and handle any file of any type, there are some