docs/manual/guide/15-alongside-emacs.org

Orgstar edits the file's text directly; there is no separate document format. When it saves, text you didn't change is written back exactly as it was read:

• A file with no changes is never rewritten.
• Untouched lines keep their bytes, including trailing whitespace, tabs, and the presence or absence of a final newline.
• Line endings are kept as they are. A file with CRLF line endings keeps them, and on the Mac the modeline shows CRLF for such a file. Orgstar doesn't convert line endings; new lines that Orgstar's commands insert end with LF.

Orgstar edits UTF-8 files, with or without a byte order mark. A file that starts with a BOM keeps it.

A file that isn't valid UTF-8 (UTF-16, Latin-1, or a file with invalid bytes) opens read-only. The window's subtitle says "Read-only: not UTF-8", undecodable bytes show as replacement characters, and commands that would change the file report that it "isn't UTF-8, so it can't be changed". Orgstar never converts such a file.

Saving replaces the file through a temporary file in the same folder (named .name.org.orgstar-…), under the system's file coordination, so iCloud and other coordinating apps see a complete file. The steps are:

1. Read the file on disk. If it changed since Orgstar last read or wrote it, keep both versions in the recovery folder and merge the change into your edits (see below).
2. Read the file again. If it changed in the meantime, start over, up to three times.
3. Replace the file. If another program replaced it between the check and the write, its version goes to the recovery folder and is merged into your edits.
4. Read the file back. If it changed right after the write, Orgstar's version goes to the recovery folder and the new disk version is merged in.

Emacs and Syncthing don't use file coordination, so these checks can't lock them out. They narrow the window in which two writers can collide, and every version a save displaces is kept in the recovery folder.

If the file keeps changing through all three attempts, the save fails with an error and your edits stay unsaved.

With save = "automatic" (the default), Orgstar saves a file one second after you stop typing. With "explicit", only ⌘S (Save) and ⌥⌘S (Save All) save. See Configuration. The iOS app always saves automatically.

The sheet shows what differs, with lines marked - on disk and + in your version, and offers:

On the Mac, Revert to File on Disk (in the command palette) loads the disk version at any time; unsaved changes go to the recovery folder.

Orgstar reads and writes files under file coordination, which is how iCloud expects apps to work. Files iCloud hasn't downloaded yet (.name.org.icloud placeholders) aren't indexed; Orgstar asks iCloud to download them and indexes them when they arrive. On iOS they appear in the Folders tab with a cloud icon until then.

Syncthing writes files without file coordination. Orgstar sees its changes through file watching and merges them as described above.

• Syncthing's temporary files (.syncthing.*) are ignored.
• Its folders .stfolder and .stversions are in the default ignored-folders.
• Conflict copies (name.sync-conflict-YYYYMMDD-HHMMSS-ID.org) are listed in the sidebar but never indexed, so they don't appear in the agenda, search or ID links.

When a file with conflict copies opens, a message says how many there are. Resolve Sync Conflicts… in the command palette (More ▸ Sync Conflict Copies on iOS) lists each copy against the file, with lines marked - in the file and + in the copy:

Each choice then moves the copy to the recovery folder and deletes it from the folder.

Any program that writes files in your folders is treated the same way: Orgstar sees the change, reloads or merges, and keeps displaced versions. Programs that write through file coordination (iCloud, File Provider apps on iOS) are seen as they write; others are seen through FSEvents on the Mac and when you return to the app on iOS.

When scanning folders, Orgstar skips Emacs lock files (.#name), backups (name~) and auto-save files (#name#), its own temporary and backup files (names containing .orgstar-), .DS_Store, .localized, and the folders in ignored-folders. With show-hidden-files = false, every dotfile and dot folder is skipped. Orgstar doesn't create or honour Emacs lock files.

Orgstar uses the first of these that is an executable file:

1. the path in the environment variable ORGSTAR_EMACS,
2. /opt/homebrew/bin/emacs,
3. /usr/local/bin/emacs,
4. /Applications/Emacs.app/Contents/MacOS/Emacs,
5. /run/current-system/sw/bin/emacs,
6. /usr/bin/emacs.

An app started from the Dock doesn't see your shell's PATH, which is why Orgstar looks in fixed places. Without Emacs, these features report "Emacs isn't installed, so …" and change nothing.

• Emacs runs with -Q: your init.el, packages and customizations aren't loaded. Org and the exporters are the versions bundled with that Emacs.
• Orgstar writes a snapshot of the buffer to a temporary folder and runs Emacs on it, so unsaved edits are included. The working directory is the file's folder.
• File-local variables marked safe apply (enable-local-variables is :safe).
• Export doesn't run source blocks (org-export-use-babel is nil). The exported file is written next to the org file, as Emacs writes it, or moved to the place you chose.
• For export and table recalculation, Emacs gets your PATH with /opt/homebrew/bin, /usr/local/bin, /Library/TeX/texbin, /usr/bin and /bin added, as source blocks do, so the programs it starts, such as pdflatex, are found when Orgstar was opened from the Dock.
• PDF export needs a LaTeX installation that Org's LaTeX exporter can run.
• A table recalculation that takes more than 60 seconds, or an export that takes more than 120 seconds, is stopped. Source blocks have a limit of 300 seconds. ⌘. (Cancel Running Task) stops a running block, export or table recalculation sooner.

Orgstar's defaults follow a common Doom Emacs setup rather than plain Emacs in several places. If you use plain Emacs on the same files, set these in config.toml to match your Emacs, or use Import from Emacs; see Configuration.

org-hide-emphasis-markers and org-pretty-entities matter for files you also edit in Emacs: Orgstar aligns tags and tables, and fills paragraphs, by the width text has on screen in your Emacs. If they don't match your Emacs, tags and tables that Orgstar aligns look misaligned in Emacs.

These behave as Emacs's defaults and can't be changed: org-log-repeat is time, fast TODO selection is on when keywords have keys, priorities are A to C with B as default unless #+PRIORITIES says otherwise, and org-use-sub-superscripts is {} for display (only x_{1} and x^{2} are lowered and raised).

The agenda selects the same entries as Org's, but shows them its own way (see The agenda):

• Rows have their own layout: the time or a status such as Due in 2d on the left, the category above the title, and the keyword and priority as badges. org-agenda-prefix-format doesn't change it; only %t in its agenda entry still decides whether a time in the heading text leaves the title.
• Days without entries are hidden unless org-agenda-show-all-dates is true.
• Today's past deadlines and past scheduled entries are gathered in an Overdue group, oldest first, rather than sorted among today's entries by urgency.
• The time grid isn't shown. The now line is, between today's timed entries.

Orgstar refuses some things with a message rather than doing something different from Emacs. These are the ones found in the current version.

Code blocks (see Code blocks):

• :cmdline is supported only for shells, dot, plantuml, mermaid and C, C++, D, Java, Fortran and Clojure.
• :post isn't supported; :prologue and :epilogue only for C, C++, D, Java, Fortran and Clojure; :stdin and :shebang only for shells.
• :session is supported only for shells and Python. C, C++, D, Java, Fortran and Clojure ignore it, as in Org.
• Clojure runs with babashka or the Clojure CLI only; other :backend values are refused.
• :var isn't supported for Ruby, JavaScript, R and awk blocks.
• Header arguments, :var values and :cache that need Lisp evaluated by Emacs are refused when Orgstar's interpreter can't evaluate them: "… is Lisp that only Emacs can evaluate; nothing was run."
• Noweb references that run a block aren't supported.
• Tangling refuses :var that would run a block, and tables and lists in :var for some languages.
• On iOS, only Emacs Lisp blocks run.

Links (see Links):

• Coderef links ([[(ref)]]) and regexp search links ([[/regexp/]]) aren't supported.
• shell: and elisp: links aren't run.

Capture templates (see Capture):

• %( escapes, which run Emacs Lisp, aren't supported.
• %[file] escapes aren't supported.

Tables and dynamic blocks (see Tables and Dates and clocking):

• Formulas outside Orgstar's own calculator go to Emacs on the Mac and are refused on iOS.
• Clock tables support the scopes nil, file, subtree and treeN; other scopes, :match and :step aren't supported.
• Dynamic blocks other than clocktable and columnview aren't supported. Column views of other files aren't supported.

Other:

• C-c C-q before the first heading (setting file tags) isn't supported.
• Priority ranges that aren't letters or numbers are refused.
• #+SETUPFILE URLs aren't fetched.
• Most #+STARTUP options for footnotes, entities, LaTeX previews, numbering and odd levels are accepted and ignored; see Configuration.
• display-line-numbers-type has no relative or visual mode.