summaryrefslogtreecommitdiff
path: root/Documentation/config.txt
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2008-02-17 01:59:20 (GMT)
committerJunio C Hamano <gitster@pobox.com>2008-02-17 01:59:20 (GMT)
commit2ac4b4b2228f3ef996db7b07aea74c4b1a796f38 (patch)
tree245c7610f3a42fef9d63a883a281dc8e3efffe8a /Documentation/config.txt
parent990732609ce735c482e571ad95767edf1d693b41 (diff)
parent21e5ad50fc5e7277c74cfbb3cf6502468e840f86 (diff)
downloadgit-2ac4b4b2228f3ef996db7b07aea74c4b1a796f38.zip
git-2ac4b4b2228f3ef996db7b07aea74c4b1a796f38.tar.gz
git-2ac4b4b2228f3ef996db7b07aea74c4b1a796f38.tar.bz2
Merge branch 'sp/safecrlf'
* sp/safecrlf: safecrlf: Add mechanism to warn about irreversible crlf conversions
Diffstat (limited to 'Documentation/config.txt')
-rw-r--r--Documentation/config.txt45
1 files changed, 45 insertions, 0 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt
index f9bdb16..f2f6a77 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -139,6 +139,51 @@ core.autocrlf::
"text" (i.e. be subjected to the autocrlf mechanism) is
decided purely based on the contents.
+core.safecrlf::
+ If true, makes git check if converting `CRLF` as controlled by
+ `core.autocrlf` is reversible. Git will verify if a command
+ modifies a file in the work tree either directly or indirectly.
+ For example, committing a file followed by checking out the
+ same file should yield the original file in the work tree. If
+ this is not the case for the current setting of
+ `core.autocrlf`, git will reject the file. The variable can
+ be set to "warn", in which case git will only warn about an
+ irreversible conversion but continue the operation.
++
+CRLF conversion bears a slight chance of corrupting data.
+autocrlf=true will convert CRLF to LF during commit and LF to
+CRLF during checkout. A file that contains a mixture of LF and
+CRLF before the commit cannot be recreated by git. For text
+files this is the right thing to do: it corrects line endings
+such that we have only LF line endings in the repository.
+But for binary files that are accidentally classified as text the
+conversion can corrupt data.
++
+If you recognize such corruption early you can easily fix it by
+setting the conversion type explicitly in .gitattributes. Right
+after committing you still have the original file in your work
+tree and this file is not yet corrupted. You can explicitly tell
+git that this file is binary and git will handle the file
+appropriately.
++
+Unfortunately, the desired effect of cleaning up text files with
+mixed line endings and the undesired effect of corrupting binary
+files cannot be distinguished. In both cases CRLFs are removed
+in an irreversible way. For text files this is the right thing
+to do because CRLFs are line endings, while for binary files
+converting CRLFs corrupts data.
++
+Note, this safety check does not mean that a checkout will generate a
+file identical to the original file for a different setting of
+`core.autocrlf`, but only for the current one. For example, a text
+file with `LF` would be accepted with `core.autocrlf=input` and could
+later be checked out with `core.autocrlf=true`, in which case the
+resulting file would contain `CRLF`, although the original file
+contained `LF`. However, in both work trees the line endings would be
+consistent, that is either all `LF` or all `CRLF`, but never mixed. A
+file with mixed line endings would be reported by the `core.safecrlf`
+mechanism.
+
core.symlinks::
If false, symbolic links are checked out as small plain files that
contain the link text. linkgit:git-update-index[1] and