docs: document symlink restrictions for dot-files
We stopped allowing symlinks for .gitmodules files in 10ecfa7649 (verify_path: disallow symlinks in .gitmodules, 2018-05-04), and we stopped following symlinks for .gitattributes, .gitignore, and .mailmap in the commits from 204333b015 (Merge branch 'jk/open-dotgitx-with-nofollow', 2021-03-22). The reasons are discussed in detail there, but we never adjusted the documentation to let users know. This hasn't been a big deal since the point is that such setups were mildly broken and thought to be unusual anyway. But it certainly doesn't hurt to be clear and explicit about it. Suggested-by: Philip Oakley <philipoakley@iee.email> Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
May 3, 2021 at 16:43 UTC
8ff06de10c12ef1f796fcefb96166133965d510e
4 files changed
+25
Documentation/gitattributes.txt
+6
@@ -1247,6 +1247,12 @@ to:
1247
[attr]binary -diff -merge -text
1248
------------
1249
1250
+NOTES
1251
+-----
1252
+
1253
+Git does not follow symbolic links when accessing a `.gitattributes`
1254
+file in the working tree. This keeps behavior consistent when the file
1255
+is accessed from the index or a tree versus from the filesystem.
1256
1257
EXAMPLES
1258
--------
Documentation/gitignore.txt
+4
@@ -149,6 +149,10 @@ not tracked by Git remain untracked.
149
To stop tracking a file that is currently tracked, use
150
'git rm --cached'.
151
152
+Git does not follow symbolic links when accessing a `.gitignore` file in
153
+the working tree. This keeps behavior consistent when the file is
154
+accessed from the index or a tree versus from the filesystem.
155
+
156
EXAMPLES
157
--------
158
Documentation/gitmailmap.txt
+7
@@ -55,6 +55,13 @@ this would also match the 'Commit Name <commit@email.xx>' above:
55
Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX>
56
--
57
58
+NOTES
59
+-----
60
+
61
+Git does not follow symbolic links when accessing a `.mailmap` file in
62
+the working tree. This keeps behavior consistent when the file is
63
+accessed from the index or a tree versus from the filesystem.
64
+
65
EXAMPLES
66
--------
67
Documentation/gitmodules.txt
+8
@@ -98,6 +98,14 @@ submodule.<name>.shallow::
98
shallow clone (with a history depth of 1) unless the user explicitly
99
asks for a non-shallow clone.
100
101
+NOTES
102
+-----
103
+
104
+Git does not allow the `.gitmodules` file within a working tree to be a
105
+symbolic link, and will refuse to check out such a tree entry. This
106
+keeps behavior consistent when the file is accessed from the index or a
107
+tree versus from the filesystem, and helps Git reliably enforce security
108
+checks of the file contents.
109
110
EXAMPLES
111
--------