HWLOC-DIFF(1)

💅 HWLOC-DIFF — bestie edition

okay so this is a page from the hwloc manual set, and honestly? it's a good one. hwloc-diff is the little tool that tells you what changed between two XML topology files. let's get into it 🦋

---

✨ NAME ✨

hwloc-diff — compute differences between two XML topologies

---

🎀 SYNOPSIS 🎀

hwloc-diff [options] <input1.xml> <input2.xml>

hwloc-diff [options] <input1.xml> <input2.xml> <output.xml>

like, two inputs minimum, and a third one if you want the diff written somewhere specific 💖

---

💅 OPTIONS 💅

• --refname <name> — use <name> as the identifier for the reference topology in the output XML difference. it's literally there to tell you which topology should be used when applying the resulting difference. and get this: hwloc-patch may use that name to automatically load the relevant reference topology XML. by default, <input1.xml> is used without its full path. so it's just the filename, no directory drama ✨
• --version — report the version and exit. that's it, that's the whole job.
• -h, --help — display the help message and exit. when you're lost, start here 🫶

---

🌸 DESCRIPTION 🌸

okay so hwloc-diff computes the difference between two XML topologies and stores the result into <output.xml> if there is one, or dumps it to stdout otherwise. very "if you don't give me a destination i'll just yell into the terminal" of it 💀

the output difference may later be applied to another topology with hwloc-patch. so it's giving reusable, portable diff energy 👑

and if you've got a whole directory of XML files and you need diffs between all of them? hwloc-compress-dir may be used for computing the diffs between all XML files in a directory. iconique.

NOTE: if some application-specific userdata were been exported to the input XMLs, they will be ignored and discarded from the output because hwloc has no way to understand and compare them. so like... it's not being shady, it genuinely cannot read them 😭

NOTE: it is highly recommended that you read the hwloc(7) overview page before reading this man page. most of the concepts described in hwloc(7) directly apply to the hwloc-diff utility. do your homework bestie, it's worth it 📚

---

🦋 EXAMPLES 🦋

hwloc-diff's operation is best described through several examples. and honestly these are kind of a vibe, let's go 💜

compute the difference between two XML topologies and output it to stdout:

$ hwloc-diff fourmi023.xml fourmi024.xml
Found 11 differences, exporting to stdout
<?xml version="1.0" encoding="UTF-8"?>
...

output the difference to file diff.xml instead:

$ hwloc-diff fourmi023.xml fourmi024.xml diff.xml
Found 11 differences, exporting to diff.xml

when the difference is too complex to be represented:

$ hwloc-diff fourmi023.xml avakas-frontend1.xml
Found 1 differences, including 1 too complex ones.
Cannot export differences to stdout

awkward. it found it, it just can't describe it. relatable honestly 🙈

directly compute the difference between two topologies and apply it to another one:

$ hwloc-diff fourmi023.xml fourmi024.xml | hwloc-patch fourmi025.xml -

the pipe is doing the heavy lifting, the trailing - is telling hwloc-patch to read from stdin. chef's kiss 🔥

---

⭐ RETURN VALUE ⭐

upon successful execution, hwloc-diff outputs the difference. the return value is 0. slay 💃

if the difference is too complex to be represented, an error is returned and the output is not generated. no output, no good, no 0.

hwloc-diff also returns nonzero if any kind of error occurs, such as (but not limited to) failure to parse the command line. so if you typo your flags, bestie, it's gonna tell you with a nonzero exit 🌈

---

👑 SEE ALSO 👑

hwloc(7), lstopo(1), hwloc-patch(1), hwloc-compress-dir(1) — go read them, they're all part of the same little hwloc family and they lowkey complete each other 💖

---

that's the whole page! 🩵 this one's from hwloc 2.15.0, dated Sep 23, 2026 — go forth and diff your topologies, bestie 🎀✨