Editing files precisely

While DataMind Oda works on a task, it can change files with a precise editing tool. The tool's edits are exact: text is replaced only when it matches the file exactly and appears once, and a change that cannot match is refused rather than guessed. This page explains the tool's four commands and the messages that can appear while Oda edits.

For Oda's everyday file tools, including how it reads files and images, see Read, write and edit files.

The four editing commands

Each command is given one full path, and each change touches one file:

Command	What it does
`view`	Shows a file's content with line numbers, or what a folder holds up to two levels deep. A folder view leaves out hidden items, `node_modules`, and Python cache directories. A file view can cover the whole file or one range of lines.
`create`	Writes a new file. If something already exists at the path, it refuses and nothing is overwritten.
`str_replace`	Replaces text that must match the file exactly and appear exactly once. There is no replace-everywhere option.
`insert`	Adds lines at a position in a file. Positions are counted from zero, and position 0 is before the first line.

A view of a long file is clipped: the beginning is kept (up to 16,000 characters by default) and the rest is marked as clipped. The note tells Oda to search the file for the line numbers it needs and read a smaller part instead.

What every edit requires

A full path. Every command names the file or folder by its full path on the computer. A path that is not complete is refused, and the message shows the full form to use instead.
Text as it is. The text being replaced must match the file exactly, down to its spacing. One character of difference is enough for the text not to be found, and the replacement is used exactly as given, with no pattern handling.
One match. The text being replaced must appear in the file exactly once. A text that appears more than once is refused rather than guessed, because Oda cannot tell which occurrence is meant; there is no option to change every occurrence in one step.
A viewed file for inserts. An insert is aimed at a position between lines, and a position alone does not show what the file holds now. Oda views the file first, and an insert into a file it has not viewed is refused until it does.
Text files only. The commands work on UTF-8 text. A binary file, such as an image or an archive, cannot be changed this way.
An allowed place. Some places on the computer are outside what the chat is allowed to change. A change there is refused before it runs, and nothing is written; see File safety and error messages.

Messages you may see

An edit is one of Oda's steps in the chat; when an edit does not go through, the message appears with that step (Tool calls in the chat covers those cards). Find your message below.

Note

A refused edit changes nothing: the file stays exactly as it was. Oda is told what went wrong and can continue or try another way.

When a path cannot be used

Message	What it means	What to do
The path `<path>` is not an absolute path, it should start with `/`. Maybe you meant /`<path>`?	The path is not complete, so no edit ran. The message shows the full form to use instead.	Nothing was changed. Give the full path, for example the one in the message.
`The path <path> does not exist. Please provide a valid path.`	There is no file or folder at that path, so no edit ran.	Check the name. If the file was moved or renamed outside DataMind Oda, tell Oda where it is now.
The path `<path>` is a directory and only the `view` command can be used on directories	The path names a folder, and a change was aimed at it. A folder can be shown, not edited.	Name the file inside the folder that Oda should change.

When an edit cannot be applied

Message	What it means	What to do
File already exists at: `<path>`. Cannot overwrite files using command `create`.	Oda tried to create a file where one already exists, and it does not overwrite files this way.	The file that is there was not touched. To change it, ask Oda to edit it; for a second file, give a different name.
No replacement was performed, old_str `<old>` did not appear verbatim in `<path>`.	The text being replaced is not in the file exactly as written: a space or a line break that differs is enough for no match.	The file was not changed. Ask Oda to view the file and make the change from the exact text it finds there.
No replacement was performed. Multiple occurrences of old_str `<old>` in lines [`<lines>`]. Please ensure it is unique	The text appears more than once, and the change is refused rather than applied to the wrong occurrence.	Ask for one change at a time, giving each enough surrounding text to be unique.
Invalid `insert_line` parameter: `<n>`. It should be within the range of lines of the file: [0, `<N>`]	The position given for inserted lines is outside the file's lines, so nothing was added.	The file was not changed. Ask Oda to view the file and insert at a position inside it.

When an editing call is incomplete

A piece of the call was missing or in the wrong form, so the edit did not run.

Message	What it means	What to do
Parameter `<p>` is required for command: `<cmd>``` / Parameter `<p>` is empty for command: ````	A required piece of the call was left out or blank.	Nothing was changed. Ask Oda to repeat the change.
Invalid `view_range`. It should be a list of two integers.	A range of lines was given in the wrong form, so nothing was shown.	Nothing was changed. Ask Oda to view the whole file, or a range that starts and ends with a line number.
The `view_range` parameter is not allowed when `path` points to a directory.	A range of lines was asked of a folder, and only a file has lines.	Ask Oda to view the folder as a list, or to read the file you meant.
Parameter `new_str` must be omitted or contain a string for command: str_replace	The replacement text was given in a form the command does not accept, so the edit did not run.	Nothing was changed. Ask Oda to repeat the change; to remove text, the replacement is left out.

When an edit goes through

The result states it plainly: New file created successfully at: <path> for a new file, and The file <path> has been edited successfully. for a change to an existing one. After a turn that changed files, the chat shows a summary of the changes; see Changed files and comparisons.

Questions, answered

Can every occurrence of a text be changed at once?

No. The editing tool replaces one match at a time, and the match must be unique: a text that appears more than once is refused, so the wrong occurrence is never changed. Ask for the changes one at a time, with enough surrounding text for each to be unique.

Why did an edit fail because the text did not appear verbatim?

The text being replaced is not in the file exactly as written: a space, an indentation or a line break that differs is enough for no match, and no replacement was made. Ask Oda to view the file and make the change from the exact text it finds there.

Why would Oda not create a file that already existed?

A new file is never written over an existing one, so an existing file cannot be lost by mistake. The file that is there stays as it is. To change it, ask Oda to edit it; for a second file, give a different name.

Why does a path message suggest a path that starts with `/`?

The editing tool names files by their full path on the computer, and the message shows the full form to use when a path is incomplete. Nothing was changed; give the full path, for example the one in the message.

Why must Oda view a file before adding lines to it?

An insert is aimed at a position between lines, and a line number alone does not show what the file holds now. Oda views the file first, and an insert into a file it has not viewed is refused until it does.

Does an edit change anything else in the file?

No. Only the text Oda was told to change is replaced, and the replacement is used exactly as given. The rest of the file, including its spacing and tabs, is left as it was.

Can Oda edit any kind of file?

No. The editing commands work on UTF-8 text. A binary file, such as an image or an archive, cannot be changed this way.

If an edit is refused, was my file changed?

No. A refused edit changes nothing: the file stays exactly as it was. Ask Oda to try the change again, for example from the exact text it finds in the file.

Why does a folder view leave some files out?

A folder view covers a folder up to two levels deep and leaves out hidden items, node_modules, and Python cache directories. If you need a file from one of those places, ask Oda to read it by name.