|
Size: 1341
Comment: +cat
|
Size: 3772
Comment: Added information about the hook
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| == Win32 extension == | ## page was renamed from Win32Extension == Win32text extension == |
| Line 7: | Line 8: |
| This extension provides automatic line ending conversion for Mercurial repositories in a Windows platform. | Core Mercurial tracks but never modifies file content, and it is thus binary safe. The different line ending conventions traditionally used in unix and windows will thus be maintained with core Mercurial. That can give annoyances and problems in mixed environments, so traditionally {{{unix2dos}}} and {{{dos2unix}}} scripts are used to manage the mess. The win32text Mercurial extension addresses this problem. |
| Line 9: | Line 10: |
| It avoids the problems due to different line ending styles when there's mixed users of windows and other platforms. The change in line convention could lead to false modification of files and is traditionally managed by {{{unix2dos}}} and {{{dos2unix}}} scripts. | === Method === The win32text extension assumes and maintains that the repository is in unix-style, and that text files in the repository thus uses \n for newline. The extension is only used on windows to convert text files, thus the name. When Mercurial reads text file content from the repository then the extension can filter and decode unix-style \n to windows-style \r\n - and it will warn if the repository file already has windows-style newlines. And when Mercurial commits text files to the repository then they will first be decoded from windows-style \r\n to unix-style \n. The remaining problem is to decided which files are text files; Mercurial intentionally doesn't track that kind of meta-data. The win32text filters are applied to files matching a pattern, and by carefully creating patterns the filters can be applied to exactly all text files in a repository. The filter specification can however not be managed by the repository, so creating complex specifications for distributed projects isn't recommended. But the filters come in two variants: A "dumb" filter which modifies anything looking like line endings in all files it is applied to, and a "clever" filter which only works on files NOT containing zero bytes. The simple heuristics used by the "clever" filter will fail in some cases, but it often works so well that it can just be applied to all files. '''Note:''' do not change the encode or decode filter settings while you have files checked out - use {{{hg update null}}} to remove any working files first. The extension also provides a hook which can be used to prevent the introduction of text files containing CRLF. This hook is normally used to enforce unix-style line endings in shared repositories, by rejecting commits coming from users who have not enabled the filters. |
| Line 13: | Line 25: |
| Enable the extension in the configuration file (hgrc): | Enable the extension in the configuration file (hgrc) and specify which filters should be used where, for example: |
| Line 18: | Line 30: |
| }}} | |
| Line 20: | Line 31: |
| Optionally set the encode and decode methods: {{{ |
|
| Line 26: | Line 34: |
| # ** = cleverencode: | ** = cleverencode: |
| Line 31: | Line 39: |
| # *.txt = dumbencode: | # **.txt = dumbencode: |
| Line 37: | Line 45: |
| # ** = cleverdecode: | ** = cleverdecode: |
| Line 43: | Line 51: |
| }}} If you apply these settings globally but wish to override them for a specific repository, use the "!" syntax in the repository hgrc file to remove the filters. {{{ [extensions] # Disable the extension hgext.win32text= ! [encode] # Disable the encoding filter ** = ! [decode] # Disable the decoding filter ** = ! }}} To enable the hook, add these lines {{{ [hooks] # Reject commits which would introduce windows-style text" files pretxncommit.crlf = python:hgext.win32text.forbidcrlf |
Win32text extension
This extension is currently being distributed along with Mercurial.
Author: Bryan O'Sullivan
Overview
Core Mercurial tracks but never modifies file content, and it is thus binary safe. The different line ending conventions traditionally used in unix and windows will thus be maintained with core Mercurial. That can give annoyances and problems in mixed environments, so traditionally unix2dos and dos2unix scripts are used to manage the mess. The win32text Mercurial extension addresses this problem.
Method
The win32text extension assumes and maintains that the repository is in unix-style, and that text files in the repository thus uses \n for newline. The extension is only used on windows to convert text files, thus the name.
When Mercurial reads text file content from the repository then the extension can filter and decode unix-style \n to windows-style \r\n - and it will warn if the repository file already has windows-style newlines. And when Mercurial commits text files to the repository then they will first be decoded from windows-style \r\n to unix-style \n.
The remaining problem is to decided which files are text files; Mercurial intentionally doesn't track that kind of meta-data.
The win32text filters are applied to files matching a pattern, and by carefully creating patterns the filters can be applied to exactly all text files in a repository. The filter specification can however not be managed by the repository, so creating complex specifications for distributed projects isn't recommended. But the filters come in two variants: A "dumb" filter which modifies anything looking like line endings in all files it is applied to, and a "clever" filter which only works on files NOT containing zero bytes. The simple heuristics used by the "clever" filter will fail in some cases, but it often works so well that it can just be applied to all files.
Note: do not change the encode or decode filter settings while you have files checked out - use hg update null to remove any working files first.
The extension also provides a hook which can be used to prevent the introduction of text files containing CRLF. This hook is normally used to enforce unix-style line endings in shared repositories, by rejecting commits coming from users who have not enabled the filters.
Configuration
Enable the extension in the configuration file (hgrc) and specify which filters should be used where, for example:
[extensions] hgext.win32text= [encode] # Encode files that don't contain NUL characters. ** = cleverencode: # Alternatively, you can explicitly specify each file extension that # you want encoded (any you omit will be left untouched), like this: # **.txt = dumbencode: [decode] # Decode files that don't contain NUL characters. ** = cleverdecode: # Alternatively, you can explicitly specify each file extension that # you want decoded (any you omit will be left untouched), like this: # **.txt = dumbdecode:
If you apply these settings globally but wish to override them for a specific repository, use the "!" syntax in the repository hgrc file to remove the filters.
[extensions] # Disable the extension hgext.win32text= ! [encode] # Disable the encoding filter ** = ! [decode] # Disable the decoding filter ** = !
To enable the hook, add these lines
[hooks] # Reject commits which would introduce windows-style text" files pretxncommit.crlf = python:hgext.win32text.forbidcrlf
Usage
This extension doesn't require user interaction to work.