← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/en/eol.txt

  • Committer: Marius Kruger
  • Date: 2010-07-10 21:28:56 UTC
  • mto: (5384.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 5385.
  • Revision ID: marius.kruger@enerweb.co.za-20100710212856-uq4ji3go0u5se7hx
* Update documentation
* add NEWS

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics/en/eol.txt
 
1
End of Line Conversion
 
2
======================
 
3
 
 
4
EOL conversion is provided as a content filter where Bazaar internally
 
5
stores a canonical format but outputs a convenience format. See
 
6
``bzr help content-filters`` for general information about using these.
 
7
 
 
8
Note: Content filtering is only supported in recently added formats,
 
9
e.g. 1.14. Be sure that both the repository *and* the branch are
 
10
in a recent format. (Just setting the format on the repository
 
11
is not enough.) If content filtering does not appear to be working, use
 
12
'bzr info -v' to confirm that the branch is using "Working tree format 5"
 
13
or later.
 
14
 
 
15
EOL conversion needs to be enabled for selected file patterns using
 
16
rules. See ``bzr help rules`` for general information on defining rules.
 
17
Currently, rules are only supported in $BZR_HOME/.bazaar/rules (or
 
18
%BZR_HOME%/bazaar/2.0/rules on Windows). Branch specific rules will be
 
19
supported in a future verison of Bazaar.
 
20
 
 
21
To configure which files to filter, set ``eol`` to one of the values below.
 
22
(If a value is not set, ``exact`` is the default.)
 
23
 
 
24
 ========== ===================================== ======================
 
25
 Value      Checkout end-of-lines as              Commit end-of-lines as
 
26
 ========== ===================================== ======================
 
27
 ``native`` ``crlf`` on Windows, ``lf`` otherwise ``lf``
 
28
 ---------- ------------------------------------- ----------------------
 
29
 ``lf``     ``lf``                                ``lf``
 
30
 ---------- ------------------------------------- ----------------------
 
31
 ``crlf``   ``crlf``                              ``lf``
 
32
 ---------- ------------------------------------- ----------------------
 
33
 ``exact``  No conversion                         Exactly as in file
 
34
 ========== ===================================== ======================
 
35
 
 
36
Note: For safety reasons, no conversion is applied to any file where a null
 
37
byte is detected in the file.
 
38
 
 
39
For users working on a cross-platform project, here is a suggested rule
 
40
to use as a starting point::
 
41
 
 
42
  [name *]
 
43
  eol = native
 
44
 
 
45
If you have binary files that do not contain a null byte though, be
 
46
sure to add ``eol = exact`` rules for those as well. You can do this
 
47
by giving more explicit patterns earlier in the rules file. For example::
 
48
 
 
49
  [name *.png]
 
50
  eol = exact
 
51
 
 
52
  [name *]
 
53
  eol = native
 
54
 
 
55
If your working tree is on a network drive shared by users on different
 
56
operating systems, you typically want to force certain conventions for
 
57
certain files. In that way, if a file is created with the wrong line
 
58
endings or line endings get mixed during editing, it gets committed
 
59
correctly and gets checked out correctly. For example::
 
60
 
 
61
  [name *.bat]
 
62
  eol = crlf
 
63
 
 
64
  [name *.sh]
 
65
  eol = lf
 
66
 
 
67
  [name *]
 
68
  eol = native
 
69
 
 
70
If you take the care to create files with their required endings, you can
 
71
achieve *almost* the same thing by using ``eol = exact``. It is slightly
 
72
safer to use ``lf`` and ``crlf`` though because edits accidentally
 
73
introducing mixed line endings will be corrected during commit for files
 
74
with those settings.
 
75
 
 
76
If you have sample test data that deliberately has text files with mixed
 
77
newline conventions, you can ask for those to be left alone like this::
 
78
 
 
79
  [name test_data/]
 
80
  eol = exact
 
81
 
 
82
  [name *]
 
83
  eol = native
 
84
 
 
85
Note that ``exact`` does not imply the file is binary but it does mean
 
86
that no conversion of end-of-lines will be done. (Bazaar currently relies
 
87
of content analysis to detect binary files for commands like ``diff``.
 
88
In the future, a ``binary = true`` rule may be added but it is not
 
89
supported yet.)
 
90
 
 
91
If you have an existing repository with text files already stored using
 
92
Windows newline conventions (``crlf``), then you may want to keep using that
 
93
convention in the repository. Forcing certain files to this convention
 
94
may also help users who do not have rules configured. To do this, set
 
95
``eol`` to one of the values below.
 
96
 
 
97
 ============================ ======================== ======================
 
98
 Value                        Checkout end-of-lines as Commit end-of-lines as
 
99
 ============================ ======================== ======================
 
100
 ``native-with-crlf-in-repo`` ``crlf`` on Windows,     ``crlf``
 
101
                              ``lf`` otherwise
 
102
 ---------------------------- ------------------------ ----------------------
 
103
 ``lf-with-crlf-in-repo``     ``lf``                   ``crlf``
 
104
 ---------------------------- ------------------------ ----------------------
 
105
 ``crlf-with-crlf-in-repo``   ``crlf``                 ``crlf``
 
106
 ============================ ======================== ======================
 
107
 
 
108
For users working on an existing project that uses Windows newline
 
109
conventions in their Bazaar repository, this rule is suggested as a
 
110
starting point::
 
111
 
 
112
  [name *]
 
113
  eol = native-with-crlf-in-repo
 
114
 
 
115
For new projects, it is recommended that end-of-lines be stored as ``lf``
 
116
and that users stick to the basic settings, i.e. ``native``, ``lf``,
 
117
``crlf`` and ``exact``.
 
118
 
 
119
Note: Bazaar's EOL conversion will convert the content of files but
 
120
never reject files because a given line ending or mixed line endings
 
121
are found. A precommit hook should be used if you wish to validate
 
122
(and not just convert) content before committing.