← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/en/content-filters.txt

  • Committer: Alexander Belchenko
  • Date: 2006-07-30 16:43:12 UTC
  • mto: (1711.2.111 jam-integration)
  • mto: This revision was merged to the branch mainline in revision 1906.
  • Revision ID: bialix@ukr.net-20060730164312-b025fd3ff0cee59e
rename  gpl.txt => COPYING.txt

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics/en/content-filters.txt
1
 
Content Filters
2
 
===============
3
 
 
4
 
Content formats
5
 
---------------
6
 
 
7
 
Bazaar's content filtering allows you to store files in a different
8
 
format from the copy in your working tree.  This lets you, or your
9
 
co-developers, use Windows development tools that expect CRLF files
10
 
on projects that use other line-ending conventions. Among other things,
11
 
content filters also let Unix developers more easily work on projects
12
 
using Windows line-ending conventions, keyword expansion/compression,
13
 
and trailing spaces on lines in text files to be implicitly stripped
14
 
when committed.
15
 
 
16
 
To generalize, there are two content formats supported by Bazaar:
17
 
 
18
 
* a canonical format - how files are stored internally
19
 
* a convenience format - how files are created in a working tree.
20
 
 
21
 
 
22
 
Format conversion
23
 
-----------------
24
 
 
25
 
The conversion between these formats is done by content filters.
26
 
A content filter has two parts:
27
 
 
28
 
* a read converter - converts from convenience to canonical format
29
 
* a write converter - converts from canonical to convenience format.
30
 
 
31
 
Many of these converters will provide *round-trip* conversion,
32
 
i.e. applying the read converter followed by the write converter
33
 
gives back the original content. However, others may provide an
34
 
asymmetric conversion. For example, a read converter might strip
35
 
trailing whitespace off lines in source code while the matching
36
 
write converter might pass content through unchanged.
37
 
 
38
 
 
39
 
Enabling content filters
40
 
------------------------
41
 
 
42
 
Content filters are typically provided by plugins, so the first step
43
 
in using them is to install the relevant plugins and read their
44
 
documentation. Some plugins may be very specific about which files
45
 
they filter, e.g. only files ending in ``.java`` or ``.php``.
46
 
In other cases, the plugin may leave it in the user's hands to
47
 
define which files are to be filtered. This is typically done
48
 
using rule-based preferences. See ``bzr help rules`` for general
49
 
information about defining these.
50
 
 
51
 
 
52
 
Impact on commands
53
 
------------------
54
 
 
55
 
Read converters are only applied to commands that read content from
56
 
a working tree, e.g. status, diff and commit. For example, ``bzr diff``
57
 
will apply read converters to files in the working tree, then compare
58
 
the results to the content last committed.
59
 
 
60
 
Write converters are only applied by commands that **create files in a
61
 
working tree**, e.g. branch, checkout, update. If you wish to see the
62
 
canonical format of a file or tree, use ``bzr cat`` or ``bzr export``
63
 
respectively.
64
 
 
65
 
Note: ``bzr commit`` does not implicitly apply write converters after
66
 
comitting files. If this makes sense for a given plugin providing
67
 
a content filter, the plugin can usually achieve this effect by using a
68
 
``start_commit`` or ``post_commit`` hook say. See :doc:`hooks-help`
69
 
for more information on hooks.
70
 
 
71
 
 
72
 
Refreshing your working tree
73
 
----------------------------
74
 
 
75
 
For performance reasons, Bazaar caches the timestamps of files in
76
 
a working tree, and assumes files are unchanged if their timestamps
77
 
match the cached values. As a consequence, there are times when
78
 
you may need to explicitly ask for content filtering to be reapplied
79
 
in one or both directions, e.g. after installing or reconfiguring
80
 
plugins providing it.
81
 
 
82
 
Here are some general guidelines for doing this:
83
 
 
84
 
 * To reapply read converters, ``touch`` files, i.e. update their
85
 
   timestamp. Operations like ``bzr status`` should then reapply the
86
 
   relevant read converters and compare the end result with the
87
 
   canonical format.
88
 
 
89
 
 * To reapply write converters, ensure there are no local changes,
90
 
   delete the relevant files and run ``bzr revert`` on those files.
91
 
 
92
 
Note: In the future, it is likely that additional options will be added
93
 
to commands to make this refreshing process faster and safer.