URLWATCH-CONFIG(5)

💖 URLWATCH-CONFIG(5) — bestie's guide to configuring urlwatch 💖

okay so this is the urlwatch-config page, section 5 of the urlwatch docs, and it's literally all about how you configure urlwatch's behavior. come sit with me 🫶

---

✨ NAME ✨

urlwatch-config — Configuration of urlwatch behavior. that's it, that's the vibe. 💅

---

🌸 SYNOPSIS 🌸

urlwatch --edit-config

---

🦋 DESCRIPTION 🦋

so the global config for urlwatch is where all the basic settings live — the general behavior stuff, plus the Reporters. that's the whole thing. two big buckets. slay. ✨

---

🌈 DISPLAY 🌈

okay so urlwatch is always gonna report changes (that's literally the entire point, bestie, that's its whole job), but on top of that it also by default reports pages that are newly-added (new) and any errors (error). wanna change that? it's all in the display section of the config:

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. every single one. yes, even the boring ones. 🙈

the empty-diff settings control what happens if a page is changed, but because of like a diff_filter the diff gets reduced to the empty string. so:

• if it's set to true, urlwatch will report an (empty) change.
• if it's set to false, that change won't be included in the report at all.

💀 Filter changes are not applied for unchanged

ngl this one is important. because of the way the filtered output is stored, unchanged will always report the old contents with the filters at the time of retrieval. translation: any changes you make to a job's filter will not show up in the unchanged report. when the page actually changes, then the new filter gets applied.

for this reason, unchanged cannot be used to test filters. do not do it. instead, use the --test-filter command line option to apply your current filter to the current page contents. that's the way. 👑

---

💌 REPORTERS 💌

"Reporters" are the modules that deliver notifications through their respective medium when you enable them in the config file. they're how urlwatch slides into your DMs about a change. 📲

see urlwatch-reporters(5) for the reporter-specific options, because this page is not gonna list them all, i fear.

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

• 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, so those common config settings apply to all descendant reporters. it's giving family tree, it's giving inheritance:

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. just so you know. 🎀

here's an example config that reports on standard output in color, plus HTML e-mail using sendmail. iconic combo, honestly:

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. below. underneath. no cap. 🔥

---

🧚 JOB DEFAULTS 🧚

wanna change some settings for all your jobs at once instead of doing it one by one like a peasant? edit the job_defaults section in your config file:

job_defaults:
  all:
    diff_tool: wdiff
  url:
    ignore_connection_errors: true

the config above sets all jobs to use wdiff as the diff tool, and all url jobs to ignore connection errors. boom. done. 💅

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. 📚

---

🍓 FILES 🍓

$XDG_CONFIG_HOME/urlwatch/urlwatch.yaml

that's where the config lives. go say hi. ✨

---

⭐ SEE ALSO ⭐

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

---

👑 COPYRIGHT 👑

2024 Thomas Perl

---

and that's the whole page, bestie!! this was urlwatch documentation, urlwatch-config(5), dated Oct 28, 2024 — go forth and configure, you absolute main character. mwah 💖💅✨