Files and Git

File and preview windows

Open, edit, save, search and recover text and code files, and view pictures and HTML pages, in windows on the canvas.

On this page

Purpose

Three kinds of window show the files of your project on the canvas, next to your agents. A file window is a text and code editor. You edit, save and search in it. An image window shows a picture. An HTML window shows a web page from a file on disk. Use them to read what an agent wrote, to fix a line yourself, or to check a picture or a report. Markdown files also open in a file window, but with their own editor. See Markdown documents.

Where to find it

  • Files panel. Double-click a file row in Files in the left sidebar. The file type picks the window:

    • A picture (png, jpg, jpeg, gif, webp, svg, bmp, ico) opens an image window.
    • An HTML file (html, htm) opens an HTML window.
    • Every other file opens a file window.

    The window opens large, in focus mode. Leave focus mode to see it on the canvas. See Files panel and Canvas windows.

  • Terminal output. Hold Ctrl (Cmd on macOS) and click a file path. A file window opens on the canvas, not in focus mode. See Terminal windows.

  • If a window for the file is already open, Orkestra brings it to the front. It does not open a second window. For a file window this also works across workbenches: Orkestra switches to the workbench that holds it.

  • After a restart, every window comes back at the same place and size. Orkestra reads the file from disk again.

What you see

File window, title bar from left to right:

  • Status dot and a file icon — the dot shows the load and save state (see "States and messages").
  • File name — the default title. Hover it to see the full path. To rename the window, see Canvas windows.
  • Save-state label — a check icon or a dot, and a word: "Saved", "Unsaved changes", "Saving", "Recovered draft — not saved", or an error text.
  • Reload button — an icon button with circular arrows (tooltip "Reload from disk", or "Discard changes and reload from disk" when you have unsaved changes).
  • Save button — an icon button (tooltip "Save changes" when it is active, "Saving" while it writes, "Save" when there is nothing to save).
  • Focus and Close buttons from the window frame. The close tooltip is "Close file".
  • For a Markdown file the title bar also has a mode switch. See Markdown documents.

File window, body:

  • Editor history toolbar — two icon buttons, Undo and Redo. Markdown files have their own toolbar instead.
  • Notices — a strip above the text. It appears only when something needs your attention (see "States and messages").
  • Editor — line numbers at the left, fold arrows, coloured text, long lines wrap. Brackets match and close, and a pop-up suggests completions.
  • Find bar — a small floating bar at the top right of the editor. It opens with Ctrl+F (Cmd+F on macOS). From left to right it has:
    • Toggle Replace — a small arrow button at the left edge (tooltip "Toggle Replace").
    • Find field, with a match counter such as "2/5" or "No results".
    • Three toggles in the field: Match case (tooltip "Match case (Aa)"), Whole word (tooltip "Words") and Regular expression (tooltip "Regex (.*)").
    • Previous match (up arrow, tooltip "Previous (⇧⏎)") and Next match (down arrow, tooltip "Next (⏎)").
    • All button (tooltip "Select all occurrences") — selects every match at once.
    • Close find (X, tooltip "Close (Esc)").
    • A second row, shown after Toggle Replace: Replace field, Replace button, Replace all button.

Image window: a dot at the left of the title, the file name, Focus and Close (tooltip "Close image"). The body shows the picture on a checkerboard background. A footer shows the file path, the size in pixels ("800 × 600") and a Reload button (tooltip "Reload image from disk").

HTML window: a dot, the file name, Focus and Close (tooltip "Close page"). The body shows the page. A footer shows the file path and a Reload button (tooltip "Reload page from disk").

How to

Open a file in a file window

  1. Open Files in the left sidebar.
  2. Double-click a file row. Use a file that is not a picture and not an HTML page.

Result: a file window opens in focus mode and shows the text. While it reads, the body says "Reading file…".

Open a file from terminal output

  1. Point at a file path in the output of a terminal window.
  2. Hold Ctrl (Cmd on macOS) and click the path.

Result: a file window opens on the canvas. The path must be inside the folder of the project.

Edit and save a file

  1. Click in the text of the file window.
  2. Type your change.
  3. Press Ctrl+S (Cmd+S on macOS).

Another way: click the Save button in the title bar.

Result: the label changes from "Unsaved changes" to "Saved" and the status dot turns green. Orkestra has written the file on disk.

Undo and redo a change

  1. Click Undo in the Editor history toolbar above the text.
  2. Click Redo to bring the change back.

Result: the text goes back or forward by one step. A button is dim when there is nothing to undo or redo. Keys: Ctrl+Z (Cmd+Z on macOS) undoes. Ctrl+Y or Ctrl+Shift+Z (Cmd+Y or Cmd+Shift+Z) redoes.

Reload a file from disk

  1. Click Reload in the title bar.

Result: the window shows the text that is on disk now. If you had unsaved changes, Orkestra throws them away at once and does not ask. The message "Discarded unsaved changes" appears for 8 seconds with a Restore button.

Restore changes thrown away by a reload

Before you start, reload a file that has unsaved changes.

  1. Click Restore in the message "Discarded unsaved changes".

Result: your text comes back as an unsaved change. If you typed something after the reload, the message says "Cannot restore — the document changed since". Click Restore anyway to put the old text back over the new text.

Find text in a file

  1. Click in the text of the file window.
  2. Press Ctrl+F (Cmd+F on macOS).
  3. Type the text in the Find field.
  4. Press Enter to go to the next match.

Result: the matches are highlighted and the counter shows "1/5" (match number and total). Shift+Enter goes to the previous match. Esc closes the bar and puts the cursor back in the text.

Change how the search matches

  1. Open the find bar.
  2. Click Match case to match upper and lower case exactly.
  3. Click Whole word to match whole words only.
  4. Click Regular expression to use a pattern.

Result: a toggle that is on stays highlighted. The search runs again at once. A pattern that is not valid shows "No results".

Replace text

  1. Open the find bar.
  2. Type the text in the Find field.
  3. Click Toggle Replace.
  4. Type the new text in the Replace field.
  5. Click Replace to change the next match, or Replace all to change every match.

Result: the text changes in the editor and the file shows "Unsaved changes". Enter in the Replace field works like Replace. The buttons are dim when there are no matches. The change is on disk only after you save.

Resolve a change on disk

Before you start, have unsaved changes in a file that then changes on disk, for example when an agent edits it. A notice says "This file changed on disk while you were editing".

  1. Optional: click Compare in the notice to open a diff window. See Diff, merge, commit and Git console windows.
  2. Click Keep mine or Use disk version in the notice.

Result: Keep mine keeps your text as an unsaved change. A later save overwrites the disk version. Use disk version drops your text and the window shows the disk text.

Close a file window that has unsaved changes

  1. Click Close in the title bar.
  2. In the dialog "Unsaved changes", click Save.

Other choices in the dialog: Close & keep draft closes the window and keeps your text for later. Don't save closes the window and drops your text. Cancel keeps the window open.

Result: with Save, Orkestra writes the file and closes the window. If the write fails, the window stays open and shows the error.

Recover an unsaved draft

Before you start, close a file window with Close & keep draft, or let Orkestra stop while a file has unsaved changes.

  1. Open the same file again, or look at the window that Orkestra restored.
  2. Read the notice "Recovered your unsaved draft".
  3. Click Keep draft or Use disk version in the notice.

Result: Keep draft leaves your text in the editor as an unsaved change. Use disk version deletes the draft and shows the disk text.

If the file changed on disk after Orkestra saved the draft, the notice says "The file on disk changed since your recovered draft was saved". Both versions are kept. Use Keep mine, Use disk version or Compare.

Drop a file path into the editor

  1. Open Files in the left sidebar.
  2. Press the mouse button on a file row.
  3. Drag the row onto the text of a file window.
  4. Release the mouse button.

Result: the full path of the file appears in the text at the drop point. A task, a worktree or a session gives a link line instead. See Terminal windows.

Open a picture

  1. Open Files in the left sidebar.
  2. Double-click a picture row.

Result: an image window opens in focus mode. The body says "Loading image…" and then shows the picture, scaled down to fit the window if needed.

Open an HTML page

  1. Open Files in the left sidebar.
  2. Double-click an HTML file row.

Result: an HTML window opens in focus mode and shows the rendered page. To edit the HTML as text instead, use Open as Source in the right-click menu of the row. See Files panel.

Reload a picture or an HTML page

  1. Click Reload in the footer of the image window or the HTML window.

Result: the window reads the file from disk again. Use this when an agent has rewritten the file.

States and messages

Status dot (file window). Green: the file is loaded and saved. Amber: the file is loading. Accent colour: you have unsaved changes. Red: the file could not be read. Image and HTML windows use green, amber and red only.

Save-state label.

  • "Saved" — the buffer equals the file on disk.
  • "Unsaved changes" — you changed the text and did not save.
  • "Saving" — the write is running.
  • "Recovered draft — not saved" (warning colour) — the text came from a draft and is not yet on disk.
  • An error text (red), for example "The file no longer exists on disk." — the last save failed.

In a title bar that is 440 px wide or narrower, the words "Saved", "Unsaved changes" and "Saving" are hidden. The icon stays. Hover it to see the word. The recovered and error texts always show.

Body messages.

  • "Reading file…" — the file is loading.
  • "Cannot open this file" with a reason and a Retry button. Reasons include "The file no longer exists on disk.", "Refused: this file is outside the project.", "File exceeds the 16 MiB limit.", "This is not a regular file." and "Could not read the file."

Notices above the text.

  • "File save failed — <reason>. Your edits remain open and unsaved."
  • "This file changed on disk while you were editing" / "Your unsaved version and the version on disk are both kept" — with Keep mine, Use disk version, Compare.
  • "Recovered your unsaved draft" — with Keep draft, Use disk version.
  • "The file on disk changed since your recovered draft was saved" / "Your recovered draft and the version on disk are both kept" — with Keep mine, Use disk version, Compare.
  • "This editor may be stale because the latest disk refresh failed — <reason>. Retry when the file is available." Orkestra tries again on its own.
  • "Your saved draft could not be read — <reason>; the file on disk is shown and your draft has NOT been deleted."
  • "Your saved draft could not be saved — <reason>; your edits remain open and unsaved." The same text with "deleted" appears when a draft cannot be deleted.

Message with buttons. "Discarded unsaved changes" with Restore and a Dismiss button. It goes away after 8 seconds. "Cannot restore — the document changed since" with Restore anyway.

Close dialog. Title "Unsaved changes". Text: "<name> has unsaved changes. Choose Don't save to discard them, Close & keep draft to recover them when you reopen, or Save to write them to disk." Buttons: Cancel, Don't save, Close & keep draft, Save. While one runs, its label reads "Discarding…", "Keeping draft…" or "Saving…". Esc, a click outside the dialog and the X in its header act like Cancel. If a draft cannot be saved or deleted, the dialog stays and shows "Could not save the draft: …" or "Could not discard the saved draft: …".

Find bar. "No results" appears when the search text has no match. Previous match, Next match, All, Replace and Replace all are dim then.

Image window. "Loading image…". "Cannot open this image" with a reason and Retry.

HTML window. "Loading page…". "Cannot open this page" with a reason and Retry. The reasons are the same as for a file.

Dim buttons. Save is dim when there is nothing to save or a save is running. Reload is dim while the file loads or saves.

Limits and tips

  • Blame and file history are not available. The code has a gutter that shows who last changed each line, and a view that steps through the commits of a file. No button turns them on now, so you cannot use them.
  • Size limits. A text file, and a picture, can be up to 16 MiB. An HTML file, and each file it uses, can be up to 8 MiB.
  • Project folders only. A window opens only files inside the folders of your projects. Save never creates a file. It only overwrites a file that exists.
  • Text only. A file window reads every file as UTF-8 text. Orkestra keeps the line endings of the file when you change text. If you add or remove a line, it sets all line endings to the most common one in the file.
  • Colours. The editor colours many languages, for example JavaScript, TypeScript, Python, JSON, HTML, CSS, YAML, XML, Rust and SQL. Other file types show as plain text.
  • Terminal links. A path from terminal output always opens a file window, also for a picture or an HTML file. A line number after the path ("src/app.ts:12") is ignored. The window does not go to that line.
  • Keys. Ctrl+S (Cmd+S) also saves while the focus is on a title-bar button. Ctrl+F (Cmd+F) opens the find bar only while the text has the focus.
  • Changes on disk. Orkestra reads an open file again when you return to the Orkestra window and every 4 seconds while it has focus. A file without unsaved changes updates in place. A file with unsaved changes gets the "changed on disk" notice instead, so your text is never overwritten. Image and HTML windows do not refresh on their own. Use Reload.
  • Reload has no question. Reload with unsaved changes drops them at once. Use Restore within 8 seconds to get them back.
  • Drafts. Orkestra saves a draft of unsaved text about 1.5 seconds after you stop typing, and again when the window or the app closes. A draft holds up to 1 MiB of text. Orkestra saves the undo list with it. The list keeps up to 50 snapshots, with at most 512 KB of text in total. The oldest go first. A draft is not a file save. Only Save writes the file.
  • Recovery conflict. While the notice "The file on disk changed since your recovered draft was saved" is open, Close & keep draft does not close the window. Choose Keep mine or Use disk version first.
  • HTML pages are read-only and safe. The page shows its own HTML and CSS. Scripts never run. Plug-ins, embedded frames and forms that send data are blocked. The page cannot load anything from the internet. It can load pictures, fonts, styles and media from files inside your project folders, by a relative path or as inline data. A file it cannot load is silently left out.
  • Pictures are shown whole, scaled down to fit. There is no zoom or pan control.
  • New windows open at a default size: a picture 600 × 480 px, an HTML page 760 × 560 px. The size of a file window is a setting. See Canvas windows.