== win32lfn Extension ==

Allow manipulating long file names on Windows

''Author: Aaron Cohen <aaron@assonance.org>''

Repository: https://foss.heptapod.net/mercurial/win32lfn

'''This extension is not distributed with Mercurial'''

=== Overview ===

Windows for legacy reasons only supports files with a total path length, including directory separators, such as "/" of 260 (MAX_PATH) characters. This extension uses an alternate API in Windows which allows manipulating working copy files whose path is longer than 260 characters.

This API is a fairly recent addition to Windows, and works ok for the most part, but there are several limitations in Windows itself when it comes to long paths. If you encounter any issues while using this extension, please update the wiki page and/or email the author.

Caveats:

 * Some filesystems may have their own pathname restrictions, such as some FAT filesystems. Use NTFS or a newer FAT.
 * cmd.exe and powershell have trouble manipulating long pathnames (del, move, rename will all fail).
 * Many legacy Windows programs will have difficulty opening files with long pathnames, though most Java and 64-bit programs will work fine.
 * explorer.exe may have trouble manipulating directories with long paths, with dialogs like, "The source file name(s) are larger than is supported by the file system. Try moving to a location which has a shorter path name." To address this, use a tool other than explorer.exe or delete the affected files using "hg lfn --clean".
 * Things get more complicated if the root of your repository is more than 244 characters long, including directory separators.
     * There is no way in Windows to "cd" into a directory that long. As a result, to use hg with the repo, you will have to use "hg -R" or "hg --repository".
     * When Mercurial first starts up, it will not be able to find the ".hg" directory in such a repository until this extension is loaded. This implies that this extension must be configured in either the system-wide or user hgrc or mercurial.ini, not the per-repository ".hg/hgrc".

=== Configuration ===

Enable the extension in the appropriate configuration file (mercurial.ini):

{{{
[extensions]
win32lfn = C:\path\to\extension\win32lfn.py
}}}

=== Usage ===

Since the builtin Windows commands don't support long files very well, this extension provides one new command to assist in working with the repo at the command line.

{{{
hg lfn [--clean [--force]]
}}}

{{{
-c --clean              Prompt to delete long files
-f --force              Delete long files without prompting
}}}

With no options given, "hg lfn" will list all files in the working copy longer than 260 characters.

----
CategoryExtensionsByOthers