← 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

Latest bzr.dev

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.