path.c: document the purpose of `is_ntfs_dotgit()`

Previously, this function was completely undocumented. It is worth, though, to explain what is going on, as it is not really obvious at all. Suggested-by: Garima Singh <garima.singh@microsoft.com> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

Johannes Schindelin committed Sep 16, 2019 at 20:44 UTC 525e7fba7854c23ee3530d0bf88d75f106f14c95

1 file changed +28

path.c

+28

@@ -1302,6 +1302,34 @@ static int only_spaces_and_periods(const char *path, size_t len, size_t skip)

1302 return 1;

1303 }

1304

1305 +/*

1306 + * On NTFS, we need to be careful to disallow certain synonyms of the `.git/`

1307 + * directory:

1308 + *

1309 + * - For historical reasons, file names that end in spaces or periods are

1310 + * automatically trimmed. Therefore, `.git . . ./` is a valid way to refer

1311 + * to `.git/`.

1312 + *

1313 + * - For other historical reasons, file names that do not conform to the 8.3

1314 + * format (up to eight characters for the basename, three for the file

1315 + * extension, certain characters not allowed such as `+`, etc) are associated

1316 + * with a so-called "short name", at least on the `C:` drive by default.

1317 + * Which means that `git~1/` is a valid way to refer to `.git/`.

1318 + *

1319 + * Note: Technically, `.git/` could receive the short name `git~2` if the

1320 + * short name `git~1` were already used. In Git, however, we guarantee that

1321 + * `.git` is the first item in a directory, therefore it will be associated

1322 + * with the short name `git~1` (unless short names are disabled).

1323 + *

1324 + * When this function returns 1, it indicates that the specified file/directory

1325 + * name refers to a `.git` file or directory, or to any of these synonyms, and

1326 + * Git should therefore not track it.

1327 + *

1328 + * This function is intended to be used by `git fsck` even on platforms where

1329 + * the backslash is a regular filename character, therefore it needs to handle

1330 + * backlash characters in the provided `name` specially: they are interpreted

1331 + * as directory separators.

1332 + */

1333 int is_ntfs_dotgit(const char *name)

1334 {

1335 size_t len;