|
Size: 1292
Comment: Add category extension
|
← Revision 18 as of 2010-10-25 18:49:17 ⇥
Size: 5140
Comment: tighten up the language
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| == Win32 extension == | ## page was renamed from Win32Extension == Win32text extension == |
| Line 4: | Line 5: |
| ''Author: Bryan O'Sullivan'' {{{#!wiki warning '''Deprecation:''' The win32text extension requires each user to configure the extension again and again for each clone since the configuration is not copied when cloning. We have therefore made the EolExtension as an alternative. The EolExtension uses a version controlled file for its configuration and each clone will therefore use the right settings from the start. This extension may be removed in a future release of Mercurial. }}} To disable deprecation warnings from this extension (until you get get around to replacing win32text with eol), add these two lines to your configuration file: {{{ [win32text] warn = False }}} |
|
| Line 5: | Line 23: |
| 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 7: | Line 25: |
| 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 decide 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. === Patch operations === Operations that apply patches, e.g. {{{hg import}}} and {{{hg qpush}}}, do not honor the win32text filters; a different method is required to make these work. Mercurial can be told to ignore line endings when patching using the patch.eol configuration option; see below for an example. Without this option you will see a lot of error messages like this: {{{ patching file path/to/file Hunk #1 FAILED at 0 1 out of 1 hunks FAILED -- saving rejects to file path/to/file.rej }}} |
| Line 11: | Line 51: |
| 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 15: | Line 55: |
| hgext.win32ext= }}} |
hgext.win32text= |
| Line 18: | Line 57: |
| Optionally set the encode and decode methods: {{{ |
|
| Line 24: | Line 60: |
| # ** = cleverencode: | ** = cleverencode: |
| Line 29: | Line 65: |
| # *.txt = dumbencode: | # **.txt = dumbencode: |
| Line 35: | Line 71: |
| # ** = cleverdecode: | ** = cleverdecode: |
| Line 41: | Line 77: |
# The following lines cause patch operations to ignore eol types in # the input and patch files, and to generate CRLF line endings in the # output. [patch] eol = crlf }}} 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 |
|
| Line 48: | Line 117: |
| CategoryExtension | CategoryWindows CategoryBundledExtension |
Win32text extension
This extension is currently being distributed along with Mercurial.
Author: Bryan O'Sullivan
Deprecation: The win32text extension requires each user to configure the extension again and again for each clone since the configuration is not copied when cloning.
We have therefore made the EolExtension as an alternative. The EolExtension uses a version controlled file for its configuration and each clone will therefore use the right settings from the start.
This extension may be removed in a future release of Mercurial.
To disable deprecation warnings from this extension (until you get get around to replacing win32text with eol), add these two lines to your configuration file:
[win32text] warn = False
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 decide 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.
Patch operations
Operations that apply patches, e.g. hg import and hg qpush, do not honor the win32text filters; a different method is required to make these work. Mercurial can be told to ignore line endings when patching using the patch.eol configuration option; see below for an example.
Without this option you will see a lot of error messages like this:
patching file path/to/file Hunk #1 FAILED at 0 1 out of 1 hunks FAILED -- saving rejects to file path/to/file.rej
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: # The following lines cause patch operations to ignore eol types in # the input and patch files, and to generate CRLF line endings in the # output. [patch] eol = crlf
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.