Update element

Change title, text or properties of one element. Unknown properties are kept; status changes only via element.setStatus, and the origin of an imported element only via reqif.import (SR-057).

Command element.update. Writes files in the working tree, never to Git. It is refused while the workspace is read-only. Changes an element file, and no change can be checked against a missing or faulty metamodel.

Input

Field	Type	Required	Description
`ref`	`elementRef`	yes	UUID, short ID or identifier (e.g. SR-036), any case; several matches give ref.ambiguous.
`title`	`string`	no
`text`	`string`	no	New Markdown text of the element; the blank line after the closing `---` is not part of the text, so the text element.get gives can be passed back unchanged. A changed text gets a final line break (ADR-0004). Another element is named by a Markdown link, `[Title](reqseq:N-6010df)` with its UUID, short ID or identifier, which is written as UUID and version; `reqseq:N-6010df` alone is no link and counts for nothing.
`set`	`object`	no
`unset`	array of `key`	no
`addRelations`	`relationRefs`	no	Relations to add by kind, as relation.add adds them, in the same file write (#175). A relation the element has with a valid version is kept.
`removeRelations`	`relationRefs`	no	Relations to remove by kind, as relation.remove removes them (a UUID as given), in the same file write (#175). Nothing to remove is an info problem relation.not-found.
`repository`	`string`	no	Which of the elements ref names is meant: the workspace name of its repository, as details.candidates of ref.ambiguous give it (for example one copy of a file whose UUID another file shares, SR-088; #255). Only the elements ref names count; when none of them lies there, the error is ref.unknown with them as details.candidates.
`expectedFileSha256`	`fileSha256`	no	Write precondition (SR-106): the fileSha256 the change was made on. If the file has other bytes now, nothing is written: file.changed-on-disk, also when nothing would change.

Output

Field	Type	Required	Description
`element`	`element`	yes	An element as the commands give it: the fields of `$defs/elementFields`, and no others.
`fileSha256`	`fileSha256`	yes	Of the file as written, or as read when nothing changed (SR-106).
`files`	array of `string`	yes
`affected`	`integer`	yes	The number of directly affected elements (SR-024 AK2): the distinct elements other than this one whose files hold a relation or an inline reference to it, the elements at distance 1 of `trace.affected`. Counted only when the save changed the version (the content, D-013); 0 when only the title or properties that do not count to the version changed, or nothing changed (SR-024 AK3). For an element without a version (a value that counts has no normal form, ADR-0005) what the version is computed from is compared, so a save of only its title or status also gives 0 (#276).
`problems`	array of `problem`	no

App

In the command prompt (Ctrl+Shift+P, macOS ⌘⇧P): the action Save element. Key: Ctrl+S (macOS ⌘S).

CLI

reqseq element update, with --json for the output as JSON. Its help:

Usage: reqseq element update <ref> [options]

Change title, text or properties of one element. Unknown properties are kept;
status changes only via element.setStatus, and the origin of an imported element
only via reqif.import (SR-057).

Options:
  --ref <value>                   instead of the argument <ref>
  --title <value>
  --text <text|@file|->           New Markdown text of the element; the blank
                                  line after the closing `---` is not part of
                                  the text, so the text element.get gives can be
                                  passed back unchanged. A changed text gets a
                                  final line break (ADR-0004). Another element
                                  is named by a Markdown link,
                                  `[Title](reqseq:N-6010df)` with its UUID,
                                  short ID or identifier, which is written as
                                  UUID and version; `reqseq:N-6010df` alone is
                                  no link and counts for nothing. @file or -
                                  reads it from a file or standard input, as
                                  --input does; a text that is - or starts with
                                  @ only via --input
  --set <key=value>               repeatable; the value as JSON when it parses
                                  (a list, number, true, null), else as text:
                                  version=1.10 is the number 1.1, give
                                  'version="1.10"' for text; the last value of a
                                  key counts; keys add to --input
  --unset <value>                 repeatable
  --add-relations <key=value>     Relations to add by kind, as relation.add adds
                                  them, in the same file write (#175). A
                                  relation the element has with a valid version
                                  is kept. repeatable; the value as JSON when it
                                  parses (a list, number, true, null), else as
                                  text: version=1.10 is the number 1.1, give
                                  'version="1.10"' for text; the last value of a
                                  key counts; keys add to --input
  --remove-relations <key=value>  Relations to remove by kind, as
                                  relation.remove removes them (a UUID as
                                  given), in the same file write (#175). Nothing
                                  to remove is an info problem
                                  relation.not-found. repeatable; the value as
                                  JSON when it parses (a list, number, true,
                                  null), else as text: version=1.10 is the
                                  number 1.1, give 'version="1.10"' for text;
                                  the last value of a key counts; keys add to
                                  --input
  --repository <value>            Which of the elements ref names is meant: the
                                  workspace name of its repository, as
                                  details.candidates of ref.ambiguous give it
                                  (for example one copy of a file whose UUID
                                  another file shares, SR-088; #255). Only the
                                  elements ref names count; when none of them
                                  lies there, the error is ref.unknown with them
                                  as details.candidates.
  --expected-file-sha256 <value>  Write precondition (SR-106): the fileSha256
                                  the change was made on. If the file has other
                                  bytes now, nothing is written:
                                  file.changed-on-disk, also when nothing would
                                  change.
  --input <json|@file|->          command input as JSON: inline, from a file, or
                                  from standard input
  --workspace <path>              workspace root (default: nearest folder
                                  upwards with reqseq-workspace.yaml)
  --json                          print exactly the command output as JSON
  --yaml                          print the whole command output as YAML,
                                  problems one per line
  -h, --help                      show help

API

POST /v1/commands/element.update on the local API (reqseq serve api), with the input as the JSON body; the answer is the output.

MCP

Tool element_update of the MCP server (reqseq mcp), with the input as its arguments.