rename

Rename a form in the global library and its cwd ./forms/ twin if one exists.

basic usage

gform rename <new-name>            # TTY: pick current name → rename to <new-name>
gform rename <form> <new-name>
gform ren <form> <new-name>           # short alias
gform rename <form> <new-name> --force

Updates:

• $GFORM_HOME/forms/<from>.yaml → <to>.yaml
• ./forms/<from>.yaml → ./forms/<to>.yaml (when present)
• the name: field inside the YAML
• the stamped comment header (explanation block) — refreshed to the current canonical text

Does not rewrite form options, unique, steps, or pools (unlike init, which scaffolds a new YAML). Policy/run presets stay on the CLI (--policy); rename never invents or clears them.

Prints each renamed path on success.

force overwrite

gform rename <form> <new-name> --force

Allows replacing an existing <to>.yaml. Without --force, rename refuses if the destination exists.

reserved target names

The new name cannot be a run subcommand alias:

list · ls · view · v · last

# bad
gform rename <form> list  # reserved — pick another name

# good
gform rename <form> <new-name>

when to rename

situation	approach
typo in form name	rename fixes library + YAML name:
align name with project convention	rename then commit cwd twin
avoid collision before merge	rename one side with --force after backup

History rows and artifacts keep the old form name in their records — rename does not rewrite history.

gotchas

• Only renames files gform knows about (library + cwd twin). A random path elsewhere is untouched.
• gform run resolves by the new name immediately after rename.
• Does not rename artifact dirs or history entries — those are historical records.
• For a full copy under a new name without removing the original, use gform add with --save-as instead.

related

• list.md — confirm new name appears
• add.md — copy under new name
• delete.md — remove old name without rename
• portable.md — library paths