# Configuration

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

You can edit it with:

    urlwatch --edit-config

## 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:

    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.

Reporter-specific options are described in Reporters.

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:

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

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.

## Job Defaults

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.