docs/manual/guide/01-files-and-folders.org

Most commands are in the menu bar. The Org menu lists every org command, each with the keys that run it in the current keymap; it is disabled when no file is open.

File ▸ Command Palette… (⇧⌘P; M-x in the Emacs and Doom presets; SPC : in Doom normal state) lists every command by title with its keys. Type to filter (characters match in order, as in Quick Open), then press Return to run the top match or click one. Escape closes it. Text movement and editing commands (forward character, kill line and so on) are not listed; they are only on keys.

Several commands in this chapter are only in the palette, not in a menu: Close Other Buffers, Close All Buffers, Last Buffer, Show or Hide Tab Bar, Revert to File on Disk, Resolve Sync Conflicts… and Recovery Versions….

The toolbar's outline button does the same as View ▸ Show or Hide Outline. The sidebar is shown and hidden with the standard View menu command.

Orgstar remembers whether the outline, backlinks and inspector are shown. The outline pane's visibility is remembered for org files only: for other files it starts hidden each time you open one. Drag the divider on the outline pane's right edge to resize it (160 to 400 points; 220 by default).

Choose File ▸ Add Folder… (⇧⌘O), or click + at the bottom of the sidebar, and pick a folder. Orgstar indexes it in the background; the toolbar shows a progress indicator while it works.

Orgstar keeps a bookmark to each folder, so a folder you move or rename in Finder is followed. If a folder can't be found at launch, Orgstar reports Can't find the folder PATH. Adding a folder that is already in the sidebar does nothing.

Orgstar keeps the list of folders, the index and recovery versions in ~/Library/Application Support/Orgstar.

Click − at the bottom of the sidebar and choose the folder, or right-click the folder's header and choose Remove from Sidebar…. Confirm with Remove. The folder and its files stay on disk; only Orgstar's index entries for them are removed.

Each root is a collapsible section headed by the folder's name; hover over the name to see its full path. Roots are sorted by path. Inside a root, subfolders come first, then files, each sorted by name the way Finder sorts them. Orgstar remembers which roots you collapsed.

The sidebar lists every file in the folder, not only org files, with an icon for its kind:

Some files are never listed or indexed:

• Emacs backups (names ending in ~), auto-save files (names starting with #) and lock files (.#name);
• Syncthing's temporary files (.syncthing.*);
• Orgstar's own temporary files (names containing .orgstar-);
• .DS_Store and .localized;
• anything inside these folders: .git, .hg, .svn, .jj, .bzr, .stfolder, .stversions, .Trash, .Spotlight-V100, .fseventsd, .build, .venv, .cache, .tox, .mypy_cache, .pytest_cache, .gradle, .next, .terraform and node_modules.

Other dotfiles and dot folders are listed unless you turn off Settings ▸ General ▸ Show hidden files and folders (on by default). To change the list of ignored folders, set ignored-folders in config.toml to folder names separated by spaces; there is no control for it in Settings. See Configuration.

[orgstar]
show-hidden-files = true
ignored-folders = ".git .hg node_modules build"

Only org files (.org and .org_archive) are read by the index. Other files are listed and can be opened, but their contents are not searched.

Right-click a file or folder in the sidebar for:

• New File… — creates a file in that folder (for a file, in the folder holding it). A name without an extension gets .org. A name like projects/house creates the projects folder too. Names can't start with / or contain ... The new file opens.
• Rename… — renames the file or folder in place. The new name can't contain /. Open buffers of the file, or of files inside the folder, are saved first (in explicit save mode you are asked) and reopened under the new path.
• Show in Finder.
• Move to Trash… — moves the file or folder to the Trash after you confirm. Open buffers of it close without saving; the confirmation warns you when the file, or an open file inside the folder, has unsaved changes. You can put it back from the Trash in Finder.

Right-click a root's header for New File…, Expand or Collapse, Show in Finder and Remove from Sidebar….

How a file opens depends on what it is:

• Org files (.org, .org_archive) open in the editor with org editing.
• Text files open in the same editor as plain text. A file counts as text when macOS knows its type as text, or, for unknown types, when its first 8 KB are valid UTF-8 with no NUL bytes. Org commands report Not an org file, and the outline pane shows "No outline" when you turn it on. Files in these languages get syntax highlighting: shell (.sh, .bash, .zsh, .zshrc, .bashrc, .profile), Python, Emacs Lisp, C, C++, R, JavaScript, Java, Scheme, Clojure, Haskell, Rust, Go, Ruby, JSON, YAML, TOML and Lua.
• Everything else (images, PDFs, audio, video, archives, binary files) shows a Quick Look preview in place of the editor, with Open with Default App and Show in Finder buttons below it. The preview is not a buffer.

Text files from Finder use Orgstar only if you choose it with Open With, since Orgstar is not their default app.

Menu shortcuts (⇧⌘], ⌘W and the others) work in every preset. The Doom preset also has the Emacs preset's C-x keys in every state. The Mac preset's ⌃Tab and ⌃⇧Tab are in addition to the menu shortcuts.

Switch to Buffer asks in the echo area. The choices are the open buffers, most recently shown first, with the current buffer last. Type to narrow them, Tab to complete the top choice, Return to switch, Escape to cancel.

Close Buffer closes the current buffer and shows the buffer you showed before it. With no buffer open, ⌘W closes the window. In other windows (Agenda, Board and so on) ⌘W closes that window. File ▸ Close Window (⇧⌘W) closes the window in front.

When you close buffers with unsaved edits, what happens depends on the save mode (see Saving below): in automatic mode they are saved first; in explicit mode Orgstar asks Save, Don't Save or Cancel (Save All for several files). A buffer whose save fails or conflicts stays open.

A buffer is named after its file. When two open files have the same name, each name gets as many of its folders as it takes to tell them apart, in angle brackets, as Emacs's uniquify does with post-forward-angle-brackets:

notes.org<work>
notes.org<home>
notes.org<archive/2024>

These names show in the window title, the tab bar and Switch to Buffer.

View ▸ Show Tab Bar shows a row of tabs above the editor, one per open buffer, in buffer order. It is off by default; the setting is tab-bar in config.toml.

• Click a tab to show its buffer. Hover to see the file's full path.
• Click × to close a buffer. A dot replaces the × while the buffer has unsaved edits; clicking it also closes the buffer, with the same unsaved-changes handling as Close Buffer.

Under the outline, the backlinks pane lists headings in your folders that link to the current file (a link before a file's first heading is listed under the file's name) (Links to this file) and to the heading at the caret (Links to followed by the heading's title). It updates as you move the caret. Click an entry to open it. Turn the pane off with View ▸ Show or Hide Backlinks. Which links count is covered in Links.

View ▸ Show or Hide Columns and Clock (⌥⌘I) opens a pane on the right with column view and clocked time for the file or the current subtree. See Outlines and Dates and clocking.

Orgstar does not assume it is the only program writing your files. Emacs, Syncthing, iCloud and Git may change them too. Each save:

1. Reads the file on disk. If it has changed since Orgstar last read or wrote it, Orgstar merges those changes into the buffer first (see External changes below). If they conflict with yours, nothing is written and the buffer has a conflict.
2. Checks the file again, then writes the buffer to a temporary file in the same folder and replaces the original with it, so the file is never half-written.
3. Reads the file back. If another program wrote it at the same moment, the version that lost goes to recovery and the other program's changes are merged where possible.

Every version a save displaces goes to recovery first (see Recovery versions below). Reads and writes go through macOS file coordination, so iCloud and other coordinating programs see a consistent file.

A save keeps the file's encoding details: a UTF-8 byte order mark stays, and text you didn't change keeps its exact bytes, including CRLF line endings. Lines you add end in LF.

When a buffer conflicts with its file, automatic saving stops for that buffer, the Conflict button appears in the toolbar, and the conflict sheet opens. The sheet shows the differences: lines marked - are on disk, lines marked + are in your version, with three lines of context around each change. Choose:

After Merge with Markers the buffer holds blocks like this, which you edit and save:

<<<<<<< yours
- [ ] Call the plumber on Monday
=======
- [X] Call the plumber
>>>>>>> disk

While a conflict is unresolved, saving that buffer does nothing except reopen the sheet.

When two devices change a file before Syncthing syncs them, Syncthing keeps one version as a conflict copy beside the file, named like notes.sync-conflict-20260301-142233-ABCDEF7.org. Orgstar lists these in the sidebar in orange with a warning icon, and leaves them out of search, the agenda, ID lookup and Quick Open.

When you open a file that has conflict copies, the echo area says how many there are. Run Resolve Sync Conflicts… from the palette to compare them. Pick a copy from the menu at the top; lines marked - are in the file (as the buffer holds it) and lines marked + are in the copy. Then choose:

Each choice moves the copy to recovery and deletes it from the folder. The buffer changes as an edit you can undo, and is saved according to your save mode. When no copies are left the sheet closes.

Whenever Orgstar replaces a version of a file, it keeps a copy: your buffer when you take the disk version, the disk version when you keep yours, a version another program wrote while Orgstar saved, and resolved Syncthing copies. Orgstar keeps the last 20 versions per file in ~/Library/Application Support/Orgstar/Recovery.

Run Recovery Versions… from the palette to see the open file's versions, newest first, each with its date and why it was kept:

Select a version to see how it differs from the buffer (- in the buffer, + in the kept version). Restore puts the kept version's text in the buffer as one edit, which undo reverses; the buffer as it was goes to recovery first. Show in Finder reveals the kept file.

Files in iCloud Drive that aren't downloaded to the Mac show in the sidebar with a cloud icon and grey text, with the tooltip "Downloading from iCloud". Orgstar asks iCloud to download them, and indexes them and lets you open them when they arrive. Files iCloud removes from the Mac to save space keep their index entries until they are back, so search and the agenda still find them.