1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
.. _configuration:
Configuration
=============
.. only:: man
Synopsis
--------
urlwatch --edit-config
Description
-----------
The global configuration for urlwatch contains basic settings for the generic
behavior of urlwatch as well as the :ref:`reporters`.
.. only:: html or pdf
You can edit it with:
.. code:: bash
urlwatch --edit-config
.. _configuration_display:
Display
-------
In addition to always reporting changes (which is the whole point of urlwatch),
urlwatch by default reports newly-added (``new``) pages and errors (``error``).
You can change this behavior in the ``display`` section of the configuration:
.. code:: yaml
display:
new: true
error: true
unchanged: false
empty-diff: true
If you set ``unchanged`` to ``true``, urlwatch will always report all pages
that are checked but have not changed.
The ``empty-diff`` settings control what happens if a page is ``changed``, but
due to e.g. a ``diff_filter`` the diff is reduced to the empty string. If set
to ``true``, urlwatch will report an (empty) change. If set to ``false``, the
change will not be included in the report.
Filter changes are not applied for ``unchanged``
************************************************
Due to the way the filtered output is stored, ``unchanged`` will always report
the old contents with the filters at the time of retrieval, meaning that any
changes you do to the ``filter`` of a job will not be visible in the
``unchanged`` report. When the page changes, the new filter will be applied.
For this reason, ``unchanged`` cannot be used to test filters, you should use
the ``--test-filter`` command line option to apply your current filter to the
current page contents.
Reporters
---------
"Reporters" are the modules that deliver notifications through their
respective medium when they are enabled through the configuration file.
.. only:: html or pdf
Reporter-specific options are described in :ref:`reporters`.
.. only:: man
See :manpage:`urlwatch-reporters(5)` for reporter-specific options.
In addition to the reporter-specific options, all reporters support these
options:
* ``enabled``: *[bool]* Activate the reporter. (default: False)
* ``separate``: *[bool]* Send a report for each job rather than a combined
report for all jobs. (default: False)
Reporters are implemented in a hierarchy, such that these common configuration
settings will apply to all descendent reporters:
.. inheritance-ascii-tree:: urlwatch.reporters.ReporterBase
.. note::
Setting the `email` reporter's `html` option to `true` will cause it to
inherit from the `html` configuration.
Here is an example configuration that reports on standard
output in color, as well as HTML e-mail using ``sendmail``:
.. code:: yaml
report:
text:
details: true
footer: true
line_length: 75
html:
diff: unified
separate: true
email:
enabled: true
method: sendmail
sendmail:
path: /usr/sbin/sendmail
from: 'urlwatch@example.org'
to: 'you@example.org'
html: true
subject: '{count} changes: {jobs}'
stdout:
color: true
enabled: true
Any reporter-specific configuration must be below the ``report`` key
in the configuration.
.. _job_defaults:
Job Defaults
------------
If you want to change some settings for all your jobs, edit the
``job_defaults`` section in your config file:
.. code-block:: yaml
job_defaults:
all:
diff_tool: wdiff
url:
ignore_connection_errors: true
The above config file sets all jobs to use ``wdiff`` as diff tool, and all
``url`` jobs to ignore connection errors.
The possible sub-keys to ``job_defaults`` are:
* ``all``: Applies to all your jobs, independent of its kind
* ``shell``: Applies only to ``shell`` jobs (with key ``command``)
* ``url``: Applies only to ``url`` jobs (with key ``url``)
* ``browser``: Applies only to ``browser`` jobs (with key ``navigate``)
See :ref:`jobs` about the different job kinds and what the possible keys are.
.. only:: man
Files
-----
``$XDG_CONFIG_HOME/urlwatch/urlwatch.yaml``
See also
--------
:manpage:`urlwatch(1)`,
:manpage:`urlwatch-reporters(5)`,
:manpage:`urlwatch-intro(7)`,
:manpage:`urlwatch-cookbook(7)`
|
