diff mbox series

[3/3] docs: explain how to deal with files that are always modified

Message ID 20200912204824.2824106-4-sandals@crustytoothpaste.net (mailing list archive)
State New, archived
Headers show
Series FAQ entries for merges and modified files | expand

Commit Message

brian m. carlson Sept. 12, 2020, 8:48 p.m. UTC 
Users frequently have problems where two files 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>
---
 Documentation/gitfaq.txt | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

Comments

Martin Ågren Sept. 13, 2020, 3:13 p.m. UTC | #1 
On Sat, 12 Sep 2020 at 22:52, brian m. carlson
<sandals@crustytoothpaste.net> wrote:
>
> Users frequently have problems where two files differ only in case,

s/files/filenames/ ? Anyway, clear enough here, but let's keep it in
mind when reading the proposed FAQ entry..

> 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.

> +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 that differ in case.  Git can handle this

I think this could be clearer with something like s/that differ in case/where
their names only differ in case/, i.e., explicitly talking about the names
of the files and also sticking an "only" in there.

> +       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.

That concludes my reading of these patches. I only had some minor
comments. I think these are good entries to add to the FAQ.


Martin
diff mbox series

Patch

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 154f0cce54..494ec5dce5 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -362,6 +362,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 that differ 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