rm [-h | --help | -?] [-f | --force] [-r | --recursive] [-n | --dry-run] {object-or-path}...RM(nged)
NAME
rm - safely delete database objects, force-delete objects, or remove a child from a combination path
On this page
SYNOPSIS
DESCRIPTION
The rm command is the preferred general-purpose removal command for BRL-CAD database editing.
Each operand may be:
-
an object name
-
a parent/child path of the form comb/member or top/…/comb/member
-
a shell-style glob pattern expanded against the current database
Without options, rm performs a safe delete:
-
primitives are deleted only if they are not referenced by other objects and do not reference support objects
-
combinations are deleted only if they are unreferenced and empty
-
non-empty combinations are rejected unless -r or -f is used
If an operand contains a slash, rm treats it as a combination/member path and removes only that child reference from the parent combination. This edits the combination tree but does not delete the child object itself. If the parent combination contains multiple same-name child references, append a one-based instance suffix to the child name, such as assembly.c/bolt.s@2, to remove the second matching child instance.
To protect users of the historic combination-editing syntax, rm rejects an unforced command of the form rm comb obj … when comb is a combination and later operands are bare object names. In that case no objects are deleted. Use comb combination rm member … to remove members from the combination, use an explicit path such as rm comb/obj, or use rm -f comb obj … if direct object deletion was intended.
The rm command also supports direct object deletion, dry-run reporting, and glob expansion.
The current implementation recognizes the following options:
- -h
- --help
- -?
-
Print help and exit.
- -f
- --force
-
Force deletion. For object operands this uses the same direct-delete behavior as kill: the named object is removed immediately, even if it is referenced elsewhere. For path operands, missing paths or instances are ignored when --force is used; ambiguous same-name members still require an explicit @N instance suffix.
- -r
- --recursive
-
Recursive safe deletion. The named object and all child objects reachable below it are deleted only if the entire subtree is safe: every object exists, no object in the subtree is referenced from outside the subtree, and all child references can also be deleted. If any object in the subtree is externally referenced, the recursive delete for that operand is rejected and no objects from that subtree are deleted.
When -r is combined with -f, the top-level named object is deleted even if it is externally referenced, and descendants that are not referenced outside the walked subtree are also deleted. Shared descendants are left in place.
- -n
- --dry-run
-
Dry run. Report what would be deleted or which combination/member path would be edited, but do not modify the database.
All database changes made by rm update reference counts and remove affected names or paths from active display lists.
Common cases: "rm prim" → deletes prim if no */prim instance exists "rm -f prim" → deletes prim (children untouched) "rm -rf prim" → deletes prim and any children without */child ref. "rm comb" → always fails unless comb is empty and no */comb instance exists "rm -f comb" → deletes comb object "rm -rf comb" → deletes comb and safe-deletes children "rm path/inst" → deletes inst (if no */path/inst exists??) "rm -f path/inst" → deletes inst "rm -rf path/inst" → deletes inst
The examples below show the primary rm modes.
Example 1. Safely delete an unreferenced primitive.
- mged> rm bolt.s
-
Deletes bolt.s if it exists and is not referenced elsewhere.
Example 2. Remove one child reference from a combination.
- mged> rm assembly.c/bolt.s
-
Removes the bolt.s member from assembly.c without deleting bolt.s from the database.
Example 3. Remove a specific duplicate child reference.
- mged> rm assembly.c/bolt.s@2
-
Removes the second bolt.s member from assembly.c. This is required when a combination contains multiple same-name members with different matrices.
Example 4. Reject the old combination/member command shape.
- mged> rm assembly.c bolt.s
-
Reports an ambiguous command and leaves both assembly.c and bolt.s unchanged. Use comb assembly.c rm bolt.s or rm assembly.c/bolt.s for member removal.
Example 5. Force-delete an object.
- mged> rm -f old_part.r
-
Deletes old_part.r directly, even if other objects still reference it.
Example 6. Preview a globbed delete.
- mged> rm -n temp*
-
Lists matching database objects or paths that would be removed.
Example 7. Recursively delete an unshared hierarchy.
- mged> rm -r scratch_group.c
-
Deletes scratch_group.c and any members that are only referenced within that hierarchy. If any object below scratch_group.c is referenced from outside the hierarchy, the command reports an error and leaves the hierarchy unchanged.
Example 8. Force a recursive top-level delete while preserving shared descendants.
- mged> rm -rf scratch_group.c
-
Deletes scratch_group.c even if other objects reference it, and deletes unshared descendants below it. Descendants still referenced elsewhere remain in the database.
SEE ALSO
comb(nged), kill(nged), killall(nged), killrefs(nged), killtree(nged)
AUTHOR
BRL-CAD Team
BUG REPORTS
Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org