docs/win32-longpaths.md

   1 core.longpaths support
   2 ======================
   3
   4 Historically, Windows has limited absolute path lengths to `MAX_PATH`
   5 (260) characters.
   6
   7 Unfortunately, 260 characters is a punishing small maximum.  This is
   8 especially true for developers where dependencies may have dependencies
   9 in a folder, each dependency themselves having dependencies in a
  10 sub-folder, ad (seemingly) infinitum.
  11
  12 So although the Windows APIs _by default_ honor this 260 character
  13 maximum, you can get around this by using separate APIs.  Git honors a
  14 `core.longpaths` configuration option that allows some paths on Windows
  15 to exceed these 260 character limits.
  16
  17 And because they've gone and done it, that means that libgit2 has to
  18 honor this value, too.
  19
  20 Since `core.longpaths` is a _configuration option_ that means that we
  21 need to be able to resolve a configuration - including in _the repository
  22 itself_ in order to know whether long paths should be supported.
  23
  24 Therefore, in libgit2, `core.longpaths` affects paths in working
  25 directories _only_.  Paths to the repository, and to items inside the
  26 `.git` folder, must be no longer than 260 characters.
  27
  28 This definition is required to avoid a paradoxical setting: if you
  29 had a repository in a folder that was 280 characters long, how would
  30 you know whether `core.longpaths` support should be enabled?  Even if
  31 `core.longpaths` was set to true in a system configuration file, the
  32 repository itself may set `core.longpaths` to false in _its_ configuration
  33 file, which you could only read if `core.longpaths` were set to true.
  34
  35 Thus, `core.longpaths` must _only_ apply to working directory items,
  36 and cannot apply to the `.git` folder or its contents.