← 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

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