← 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: Martin Pool
  • Date: 2005-07-22 22:37:53 UTC
  • Revision ID: mbp@sourcefrog.net-20050722223753-7dced4e32d3ce21d
- add the start of a test for inventory file-id matching

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, lf otherwise  crlf
94
 
 ------------------------- ------------------------------ ----------------------
95
 
 lf-with-crlf-in-repo      lf                             crlf
96
 
 ------------------------- ------------------------------ ----------------------
97
 
 crlf-with-crlf-in-repo    crlf                           crlf
98
 
 ========================= ============================== ======================
99
 
 
100
 
For users working on an existing project that uses Windows newline
101
 
conventions in their Bazaar repository, this rule is suggested as a
102
 
starting point::
103
 
 
104
 
  [name *]
105
 
  eol = native-with-crlf-in-repo
106
 
 
107
 
For new projects, it is recommended that end-of-lines be stored as lf
108
 
and that users stick to the basic settings, i.e. ``native``, ``lf``,
109
 
``crlf`` and ``exact``.
110
 
 
111
 
Note: Bazaar's EOL conversion will convert the content of files but
112
 
never reject files because a given line ending or mixed line endings
113
 
are found. A precommit hook should be used if you wish to validate
114
 
(and not just convert) content before committing.