USDUPDATECRATE(1)

🌸 USDUPDATECRATE 💅

okay so bestie, welcome to the manual page for usdupdatecrate — that's usdupdatecrate 26.11.1, from the User Commands girlies, and she's here to hunt down your dusty old Pixar USD crates. sit down, hydrate, let's go 🫶

✨ DESCRIPTION ✨

so the vibe is: this is the usage line, and honestly it's giving "the group chat pinned message." here's the whole thing verbatim, no notes, keep it in your notes app:

usage: usdupdatecrate [-h] [--root DIR] [--olderThan VERSION]

[--exclude PATTERN] [--output FILE]
       [--saveWorkList FILE] [--fromWorkList FILE] [--update |
       --cleanup] [--noCleanup] [--preserveAttrs | --noPreserveAttrs]
       [--preserveOwner] [--workers N] [--batchSize N] [--walkThreads N]
       [--quiescenceTimeout SECONDS] [--perFileTimeout SECONDS]

bestie, this tool finds Pixar USD crate files (*.usd/*.usdc) that are older than a given version, and optionally updates them. literally that's the whole job 💖

and here's the default behaviour, which honestly slays because it's so safe: by default the script just reports the matching files to stdout and takes no action. cute, non-committal, low-stakes. 👑

with --update though? she gets to work: it opens each file via Sdf.Layer.FindOrOpen() and re-exports it, which causes USD to write the file at the current crate version. that's how the upgrade actually happens ✨

updates are performed safely, and no cap this is the good part: each file is exported to a sibling temp path, its new crate version is verified, and only then is the temp atomically renamed over the original. the original is left untouched on any failure. main character energy with a seatbelt on 🎀

⚠️ note on hard links — an update replaces the original directory entry via os.replace(). Any other names that were hard-linked to the original inode continue to refer to the unchanged inode and so retain the old content. so like, if you hard-linked a file, that other name is NOT getting the glow-up, bestie. it's staying exactly as it was and there is nothing you can do about it 🙈

💅 OPTIONS 💅

every single one, we're not skipping a thing, periodt.

• -h, --help — show this help message and exit. the "what does this do again" button, iconic.
• --root DIR — root directory to search (default: current working directory). the starting point, the home base, the place she starts snooping 🌸
• --olderThan VERSION — identify crate files with version older than this, formatted major.minor.patch, default 0.8.0. so it's a threshold thing — anything below it is getting flagged, no exceptions 💀
• --exclude PATTERN — exclude files whose path relative to --root matches this fnmatch pattern. may be specified multiple times (stack 'em, bestie). excluded subdirectories are pruned before descent — like, she won't even go in there, she's not looking, she doesn't want to know 🦋
• --output FILE — write the matching file list to FILE instead of stdout. for when you want receipts, saved, in a file.
• --saveWorkList FILE — save the deduplicated to-update file list to FILE before any update runs. useful as a manual two-step staging point or for crash recovery. so if things go sideways you have the list, and honestly that's iykyk 🧚
• --fromWorkList FILE — read candidate files from FILE instead of walking --root. when this is set, --root, --exclude, and --walkThreads are ignored. literally they do not get a vote 👑
• --update — update matched files by re-exporting them via Sdf.Layer. this is the actual "do the thing" flag. the one that makes it happen 🔥
• --cleanup — standalone mode: walk --root and remove stale *.usdupdatecrate.*.tmp.* files left behind by crashed or killed prior runs, then exit. honors --exclude and --walkThreads. so she cleans up the mess from the last girl's shift and goes home 🎀
• --noCleanup — during an --update run, skip the implicit removal of stale temp files discovered by the walk. has no effect in --cleanup mode (which is itself a cleanup — like, girl, that's the whole point, why would you turn off the cleanup of the cleanup 😭)
• --preserveAttrs — preserve the original file's mode and group on the updated file. if either cannot be matched (e.g. you are not a member of the original's group), the update for that file is treated as failed and the original is left untouched. the owner is not preserved unless --preserveOwner is also given. default: on (POSIX), unsupported (Windows). respect the original, she has a whole identity 🫶
• --noPreserveAttrs — disable preservation of the original mode and group. updated files take on the running user's primary group (or the directory's group, if it is setgid) and a umask-respecting mode. a fresh start, a clean slate, a rebrand 💜
• --preserveOwner — also preserve the original file's owner. off by default because changing a file's owner requires root; without it, updated files are owned by the running user. a file whose owner cannot be set is treated as failed and left untouched. POSIX only. so like, if you don't have root, don't get cute, ok? 🔥
• --workers N — explicit number of worker processes. overrides --batchSize. you say how many, that's how many 💀
• --batchSize N — number of files per pool task (default: 16). files are split into batches of this size and dispatched across workers via imap_unordered. smaller is safer (smaller crash blast radius, better work-stealing); larger amortizes per-task overhead. ignored if --workers is given. so it's a tradeoff, choose your fighter ✨
• --walkThreads N — number of threads for parallel directory enumeration (default: 32). set to 1 to use a single-threaded os.walk() instead. old school, one thread, no drama 🌈
• --quiescenceTimeout SECONDS — update pool driver: if no chunk-result arrives for this many seconds, treat any not-yet-completed chunks as crashed/hung and recover them via per-file subprocess isolation (default: 120). raise this if you have legitimately long-running chunks. so if a chunk's just being slow and dramatic, give it more time before assuming the worst 🙈
• --perFileTimeout SECONDS — recovery: hard cap on a single file's isolated subprocess (default: 60). if exceeded, the subprocess is terminated and the file recorded as an ERROR_CRASH. that's the hard limit, bestie, no negotiating ⌛

and that's the whole page, mwah 💋

sign-off szn — this whole vibe is usdupdatecrate 26.11.1, stamped October 2026, and yes the footer said USDUPDATECRATE(1) one last time because she's consistent like that. go forth, update those crates, and remember: the original is left untouched on any failure, so honestly, you literally cannot lose. 🎀✨💖