URLWATCH-CONFIG(5) urlwatch URLWATCH-CONFIG(5)

urlwatch-config - Configuration of urlwatch behavior

urlwatch --edit-config

The global configuration for urlwatch contains basic settings for the generic behavior of urlwatch as well as the Reporters.

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:

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.

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" are the modules that deliver notifications through their respective medium when they are enabled through the configuration file.

See urlwatch-reporters(5) for reporter-specific options.

In addition to the reporter-specific options, all reporters support these options:

  • enable: [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:

html
text
├───stdout
├───email
├───ifttt
├───webservice
│   ├───pushover
│   └───pushbullet
├───mailgun
├───telegram
├───slack
│   └───mattermost
├───discord
├───xmpp
├───prowl
└───shell
markdown
└───matrix

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:

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.

If you want to change some settings for all your jobs, edit the job_defaults section in your config file:

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 Jobs about the different job kinds and what the possible keys are.

$XDG_CONFIG_HOME/urlwatch/urlwatch.yaml

urlwatch(1), urlwatch-reporters(5), urlwatch-intro(7), urlwatch-cookbook(7)

2023 Thomas Perl

May 3, 2023