.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH USDUPDATECRATE "1" "September 2026" "usdupdatecrate 26.08" "User Commands"
.SH NAME
usdupdatecrate \- manual page for usdupdatecrate 26.08
.SH DESCRIPTION
usage: usdupdatecrate [\-h] [\-\-root DIR] [\-\-olderThan VERSION]
.TP
[\-\-exclude PATTERN] [\-\-output FILE]
[\-\-saveWorkList FILE] [\-\-fromWorkList FILE] [\-\-update |
\fB\-\-cleanup]\fR [\-\-noCleanup] [\-\-preserveAttrs |
\fB\-\-noPreserveAttrs]\fR [\-\-workers N] [\-\-batchSize N]
[\-\-walkThreads N] [\-\-quiescenceTimeout SECONDS]
[\-\-perFileTimeout SECONDS]
.PP
Find and optionally update Pixar USD crate (.usd/.usdc) files older than a
given version.
.PP
By default the script reports matching files to stdout and takes no action.
With \fB\-\-update\fR it opens each file via Sdf.Layer.FindOrOpen() and re\-exports
it, which causes USD to write the file at the current crate version.
.PP
Updates are performed safely: 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.
.PP
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.
.SS "options:"
.TP
\fB\-h\fR, \fB\-\-help\fR
show this help message and exit
.TP
\fB\-\-root\fR DIR
Root directory to search (default: current working
directory).
.TP
\fB\-\-olderThan\fR VERSION
Identify crate files with version older than this
(major.minor.patch, default: 0.8.0).
.TP
\fB\-\-exclude\fR PATTERN
Exclude files whose path relative to \fB\-\-root\fR matches
this fnmatch pattern. May be specified multiple times.
Excluded subdirectories are pruned before descent.
.TP
\fB\-\-output\fR FILE
Write matching file list to FILE instead of stdout.
.TP
\fB\-\-saveWorkList\fR 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.
.TP
\fB\-\-fromWorkList\fR FILE
Read candidate files from FILE instead of walking
\fB\-\-root\fR. \fB\-\-root\fR, \fB\-\-exclude\fR, and \fB\-\-walkThreads\fR are
ignored when this is set.
.TP
\fB\-\-update\fR
Update matched files by re\-exporting them via
Sdf.Layer.
.TP
\fB\-\-cleanup\fR
Standalone mode: walk \fB\-\-root\fR and remove stale
*.usdupdatecrate.*.tmp.* files left behind by crashed
or killed prior runs, then exit. Honors \fB\-\-exclude\fR and
\fB\-\-walkThreads\fR.
.TP
\fB\-\-noCleanup\fR
During an \fB\-\-update\fR run, skip the implicit removal of
stale temp files discovered by the walk. Has no effect
in \fB\-\-cleanup\fR mode (which is itself a cleanup).
.TP
\fB\-\-preserveAttrs\fR
Preserve the original file's mode and ownership on the
updated file. If the mode or ownership cannot be
matched (e.g. insufficient privilege to chown), the
update for that file is treated as failed and the
original is left untouched. Default: on (POSIX),
unsupported (Windows).
.TP
\fB\-\-noPreserveAttrs\fR
Disable preservation of original mode and ownership.
Updated files take on the running user's uid/gid and
umask\-respecting mode.
.TP
\fB\-\-workers\fR N
Explicit number of worker processes. Overrides
\fB\-\-batchSize\fR.
.TP
\fB\-\-batchSize\fR 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 \fB\-\-workers\fR is
given.
.TP
\fB\-\-walkThreads\fR N
Number of threads for parallel directory enumeration
(default: 32). Set to 1 to use a single\-threaded
os.walk() instead.
.TP
\fB\-\-quiescenceTimeout\fR 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.
.TP
\fB\-\-perFileTimeout\fR 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.