HWLOC-PATCH(1)

💅 HWLOC-PATCH 💅

okay so bestie, welcome to hwloc-patch — it lives over in the hwloc manual family, and it's the little utility that takes a topology difference and slaps it onto an existing XML topology. yes, it's giving ✨surgery for topology files✨ and honestly? obsessed.

---

🌸 NAME 🌸

hwloc-patch — apply a topology difference to an existing XML topology. that's it, that's the whole vibe. 🎀

---

🦋 SYNOPSIS 🦋

hwloc-patch [options] [<topology.xml> | refname] [<diff.xml> | -]
[<output.xml> | -]

hwloc-patch [options] [<topology.xml> | refname] [<diff.xml> | -]

so there are literally two shapes you can call it in — one of them lets you also point at an output spot, the other one doesn't (and lowkey that means it patches in place, we'll get to that). 🫶

---

✨ OPTIONS ✨

• -R, --reverse — flip it 🔄 reverse the sense of the difference file. yes literally, the whole patch goes the other direction.
• --dry-run — check whether the patch would apply, but do not actually write the result out anywhere. it's the "just looking 🧐" option, no cap.
• --version — report the version and exit. boom, done, bye 💖
• -h, --help — display the help message and exit. the classic, the icon, the main character 👑

---

💜 DESCRIPTION 💜

so like, hwloc-patch loads the difference between two topologies from an XML file (or from standard input, if you're being spicy) and applies it to an existing topology, generating a new, modified one. it's literally a glow-up for your topology file 💅

that XML difference may have been computed earlier with hwloc-diff or hwloc-compress-dir. iykyk.

here's how the output situation works, because this is the part that trips people up:

• if <output.xml> is given, the new, modified topology gets stored in that new file 🍓
• if - is given as an output, the modified topology is sent to stdout 🌈
• if no output is given, <topology.xml> is modified in place 🫣 (yes, in place. the original. gone. be sure bestie!!)

and then there's refname — if refname is given instead of <topology.xml>, the input topology filename is automatically guessed by reading the refname field of the XML diff file. so you don't have to type the filename at all, the diff file just knows. slay. ✨ by default, hwloc-diff generates XML diffs with the right reference topology filename (without any path prefix), so this Just Works.

if - is given instead of <diff.xml>, the topology difference is read from standard input 🧚

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 patch them 😭 not its fault, it just can't read them, okay?

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-patch utility. do your homework bestie, it's for your own good 🎀

---

🎀 EXAMPLES 🎀

hwloc-patch's operation is best described through several examples. and honestly, examples are the moment, they ate. let's go 🔥

apply a XML topology difference file to an existing topology:

$ hwloc-patch fourmi023.xml diff.xml fourmi023-new.xml

check if a XML topology difference file could apply to an existing topology but do not apply it:

$ hwloc-patch --dry-run fourmi023.xml diff.xml

apply a XML topology difference file whose refname field contains the right input topology:

$ hwloc-patch refname diff.xml fourmi023-new.xml

apply a XML topology from the standard intput:

$ cat diff.xml | hwloc-patch fourmi023.xml - fourmi023-new.xml

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

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

---

⭐ RETURN VALUE ⭐

upon successful execution, hwloc-patch outputs the modified topology. the return value is 0 ✅

hwloc-patch also returns nonzero if any kind of error occurs, such as (but not limited to) failure to parse the command line 💀 so like, always check your exit codes, bestie. fr fr.

---

🦋 SEE ALSO 🦋

hwloc(7), lstopo(1), hwloc-diff(1), hwloc-compress-dir(1)

---

okay that's the whole page, you're officially a hwloc-patch girlie now 👑 version 2.15.0, dated Sep 23, 2026 — go forth and patch responsibly, mwah 💖🎀🫶