krz/orgstar

A native macOS editor for org-mode files. editor org-mode swift

guide/01-files-and-folders.html

pages
orgstar/guide/01-files-and-folders.html history · blame · raw

322 lines · 34633 bytes

  1<!DOCTYPE html>
  2<html lang="en">
  3<head>
  4<meta charset="utf-8">
  5<meta name="viewport" content="width=device-width, initial-scale=1">
  6<title>Files, folders and buffers &middot; Orgstar</title>
  7<meta name="description" content="Adding folders, opening files, working with buffers, searching, saving, and how Orgstar handles changes made outside it.">
  8<link rel="icon" href="../favicon.svg" type="image/svg+xml">
  9<link rel="stylesheet" href="../theme.css">
 10<link rel="stylesheet" href="../syntax.css">
 11<link rel="stylesheet" href="../style.css">
 12</head>
 13<body>
 14<header class="site">
 15<a class="site-title" href="../index.html">Orgstar</a>
 16<nav>
 17<a href="../install.html">Install</a>
 18<a href="../quickstart.html">Quick start</a>
 19<a href="index.html">Manual</a>
 20</nav>
 21</header>
 22<main>
 23<h1>Files, folders and buffers</h1>
 24<p class="lede">Orgstar works on folders of files you add to its sidebar, keeps each open file in a buffer, saves on its own, and merges changes other programs make to the same files.</p>
 25<nav class="toc" aria-label="On this page">
 26<h2>On this page</h2>
 27<ul>
 28<li><a href="#the-window">The window</a>
 29<ul>
 30<li><a href="#menus-and-the-command-palette">Menus and the command palette</a></li>
 31<li><a href="#showing-and-hiding-panes">Showing and hiding panes</a></li>
 32</ul></li>
 33<li><a href="#folders">Folders</a>
 34<ul>
 35<li><a href="#adding-a-folder">Adding a folder</a></li>
 36<li><a href="#removing-a-folder">Removing a folder</a></li>
 37<li><a href="#what-the-sidebar-lists">What the sidebar lists</a></li>
 38<li><a href="#creating-renaming-and-trashing-files">Creating, renaming and trashing files</a></li>
 39</ul></li>
 40<li><a href="#opening-files">Opening files</a>
 41<ul>
 42<li><a href="#files-that-aren-t-org">Files that aren&#x27;t org</a></li>
 43</ul></li>
 44<li><a href="#buffers">Buffers</a>
 45<ul>
 46<li><a href="#buffer-commands">Buffer commands</a></li>
 47<li><a href="#buffer-names">Buffer names</a></li>
 48<li><a href="#the-tab-bar">The tab bar</a></li>
 49</ul></li>
 50<li><a href="#searching-your-notes">Searching your notes</a></li>
 51<li><a href="#the-outline-pane">The outline pane</a>
 52<ul>
 53<li><a href="#backlinks">Backlinks</a></li>
 54<li><a href="#inspector">Inspector</a></li>
 55</ul></li>
 56<li><a href="#saving">Saving</a>
 57<ul>
 58<li><a href="#how-a-save-works">How a save works</a></li>
 59</ul></li>
 60<li><a href="#external-changes">External changes</a>
 61<ul>
 62<li><a href="#conflicts">Conflicts</a></li>
 63<li><a href="#syncthing-conflict-copies">Syncthing conflict copies</a></li>
 64<li><a href="#recovery-versions">Recovery versions</a></li>
 65<li><a href="#icloud">iCloud</a></li>
 66</ul></li>
 67<li><a href="#encodings-and-line-endings">Encodings and line endings</a></li>
 68<li><a href="#on-ios">On iOS</a></li>
 69</ul>
 70</nav>
 71<h2 id="the-window">The window</h2>
 72<p>Orgstar has one main window, titled with the name of the buffer it shows. From left to right it holds:</p>
 73<ul>
 74<li>the <strong>sidebar</strong>, listing the folders you added and the files in them;</li>
 75<li>the <strong>outline pane</strong>, listing the headings of the open file, with the <strong>backlinks pane</strong> under it;</li>
 76<li>the <strong>editor</strong>, with the optional tab bar above it and the modeline and echo area below it;</li>
 77<li>the <strong>inspector</strong>, hidden by default, showing column view and clocked time.</li>
 78</ul>
 79<p>The toolbar holds a button that shows or hides the outline pane, a progress indicator while Orgstar indexes your folders, the running clock (see <a href="06-dates-and-clocking.html">Dates and clocking</a>), a <code class="verbatim">Conflict</code> button when the open file has a conflict (see <em>Conflicts</em> below), and the search field.</p>
 80<p>The window title is the buffer name (see <em>Buffer names</em> below). When the open file is not UTF-8, the subtitle reads <code class="verbatim">Read-only: not UTF-8</code>. The close button shows the unsaved-changes dot while any open buffer has unsaved edits.</p>
 81<p>With no folders added, the editor area reads "Add a folder of org files". With folders but no open file, it reads "Choose a file" and suggests <code class="verbatim">⌘P</code>.</p>
 82<p>The Agenda, Board, Clock Report and Capture windows are separate; they are covered in <a href="07-agenda.html">Agenda</a>, <a href="06-dates-and-clocking.html">Dates and clocking</a> and <a href="08-capture.html">Capture</a>. Closing the main window quits Orgstar when no other window is open.</p>
 83<h3 id="menus-and-the-command-palette">Menus and the command palette</h3>
 84<p>Most commands are in the menu bar. The <code class="verbatim">Org</code> menu lists every org command, each with the keys that run it in the current keymap; it is disabled when no file is open.</p>
 85<p>File ▸ Command Palette… (<code class="verbatim">⇧⌘P</code>; <code class="verbatim">M-x</code> in the Emacs and Doom presets; <code class="verbatim">SPC :</code> 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 <code class="verbatim">Return</code> to run the top match or click one. <code class="verbatim">Escape</code> closes it. Text movement and editing commands (forward character, kill line and so on) are not listed; they are only on keys.</p>
 86<p>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….</p>
 87<h3 id="showing-and-hiding-panes">Showing and hiding panes</h3>
 88<table>
 89<thead>
 90<tr><th>Menu item</th><th>Shortcut</th><th>Palette title</th></tr>
 91</thead>
 92<tbody>
 93<tr><td>View ▸ Show or Hide Outline</td><td><code class="verbatim">⌥⌘O</code></td><td>Show or Hide Outline</td></tr>
 94<tr><td>View ▸ Show or Hide Backlinks</td><td></td><td>Show or Hide Backlinks</td></tr>
 95<tr><td>View ▸ Show or Hide Columns and Clock</td><td><code class="verbatim">⌥⌘I</code></td><td>Show or Hide Columns and Clock</td></tr>
 96<tr><td>View ▸ Show Tab Bar</td><td></td><td>Show or Hide Tab Bar</td></tr>
 97</tbody>
 98</table>
 99<p>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.</p>
100<p>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).</p>
101<h2 id="folders">Folders</h2>
102<p>Orgstar does not open a single folder like a project. You add any number of folders, called roots, and each appears as a section of the sidebar. Orgstar indexes every org file in them for search, the agenda, refiling, backlinks and IDs.</p>
103<h3 id="adding-a-folder">Adding a folder</h3>
104<p>Choose File ▸ Add Folder… (<code class="verbatim">⇧⌘O</code>), or click <code class="verbatim">+</code> 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.</p>
105<p>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 <code class="verbatim">Can't find the folder PATH.</code> Adding a folder that is already in the sidebar does nothing.</p>
106<p>Orgstar keeps the list of folders, the index and recovery versions in <code class="verbatim">~/Library/Application Support/Orgstar</code>.</p>
107<h3 id="removing-a-folder">Removing a folder</h3>
108<p>Click <code class="verbatim">−</code> at the bottom of the sidebar and choose the folder, or right-click the folder's header and choose Remove from Sidebar…. Confirm with <code class="verbatim">Remove</code>. The folder and its files stay on disk; only Orgstar's index entries for them are removed.</p>
109<h3 id="what-the-sidebar-lists">What the sidebar lists</h3>
110<p>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.</p>
111<p>The sidebar lists every file in the folder, not only org files, with an icon for its kind:</p>
112<table>
113<thead>
114<tr><th>Icon</th><th>File</th></tr>
115</thead>
116<tbody>
117<tr><td>document</td><td><code class="verbatim">.org</code></td></tr>
118<tr><td>archive box</td><td><code class="verbatim">.org_archive</code></td></tr>
119<tr><td>orange warning sign</td><td>a Syncthing conflict copy (see <em>Syncthing conflict copies</em> below)</td></tr>
120<tr><td>photo</td><td>an image</td></tr>
121<tr><td>rich document</td><td>a PDF</td></tr>
122<tr><td>play button</td><td>audio or video</td></tr>
123<tr><td><code class="verbatim">&lt;/&gt;</code></td><td>source code or a script</td></tr>
124<tr><td>plain document</td><td>other text</td></tr>
125<tr><td>cloud with arrow</td><td>an iCloud file still downloading (see <em>iCloud</em> below)</td></tr>
126</tbody>
127</table>
128<p>Some files are never listed or indexed:</p>
129<ul>
130<li>Emacs backups (names ending in <code class="verbatim">~</code>), auto-save files (names starting with <code class="verbatim">#</code>) and lock files (<code class="verbatim">.#name</code>);</li>
131<li>Syncthing's temporary files (<code class="verbatim">.syncthing.*</code>);</li>
132<li>Orgstar's own temporary files (names containing <code class="verbatim">.orgstar-</code>);</li>
133<li><code class="verbatim">.DS_Store</code> and <code class="verbatim">.localized</code>;</li>
134<li>anything inside these folders: <code class="verbatim">.git</code>, <code class="verbatim">.hg</code>, <code class="verbatim">.svn</code>, <code class="verbatim">.jj</code>, <code class="verbatim">.bzr</code>, <code class="verbatim">.stfolder</code>, <code class="verbatim">.stversions</code>, <code class="verbatim">.Trash</code>, <code class="verbatim">.Spotlight-V100</code>, <code class="verbatim">.fseventsd</code>, <code class="verbatim">.build</code>, <code class="verbatim">.venv</code>, <code class="verbatim">.cache</code>, <code class="verbatim">.tox</code>, <code class="verbatim">.mypy_cache</code>, <code class="verbatim">.pytest_cache</code>, <code class="verbatim">.gradle</code>, <code class="verbatim">.next</code>, <code class="verbatim">.terraform</code> and <code class="verbatim">node_modules</code>.</li>
135</ul>
136<p>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 <code class="verbatim">ignored-folders</code> in <code class="verbatim">config.toml</code> to folder names separated by spaces; there is no control for it in Settings. See <a href="13-configuration.html">Configuration</a>.</p>
137<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">orgstar</span><span class="punctuation definition table toml">]</span>
138<span class="variable other key toml">show-hidden-files</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span>
139<span class="variable other key toml">ignored-folders</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>.git .hg node_modules build<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
140<p>Only org files (<code class="verbatim">.org</code> and <code class="verbatim">.org_archive</code>) are read by the index. Other files are listed and can be opened, but their contents are not searched.</p>
141<h3 id="creating-renaming-and-trashing-files">Creating, renaming and trashing files</h3>
142<p>Right-click a file or folder in the sidebar for:</p>
143<ul>
144<li>New File… — creates a file in that folder (for a file, in the folder holding it). A name without an extension gets <code class="verbatim">.org</code>. A name like <code class="verbatim">projects/house</code> creates the <code class="verbatim">projects</code> folder too. Names can't start with <code class="verbatim">/</code> or contain <code class="verbatim">..</code>. The new file opens.</li>
145<li>Rename… — renames the file or folder in place. The new name can't contain <code class="verbatim">/</code>. 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.</li>
146<li>Show in Finder.</li>
147<li>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.</li>
148</ul>
149<p>Right-click a root's header for New File…, Expand or Collapse, Show in Finder and Remove from Sidebar….</p>
150<h2 id="opening-files">Opening files</h2>
151<p>Click a file in the sidebar to open it. Other ways:</p>
152<ul>
153<li><strong>Quick Open</strong>: File ▸ Quick Open… (<code class="verbatim">⌘P</code>; <code class="verbatim">C-x C-f</code> in the Emacs and Doom presets; <code class="verbatim">SPC SPC</code>, <code class="verbatim">SPC .</code> or <code class="verbatim">SPC f f</code> in Doom normal state). Type part of a file's path below its root. Characters match in order, not necessarily next to each other; matches at the start of a word and runs of consecutive characters rank higher, and shorter paths win ties. Up to 50 matches show, with each file's name and path. The top match is selected; <code class="verbatim">↑</code> and <code class="verbatim">↓</code>, or <code class="verbatim">C-p</code> and <code class="verbatim">C-n</code>, move the selection. Press <code class="verbatim">Return</code> to open the selected match or click any match; <code class="verbatim">Escape</code> closes the list. Syncthing conflict copies are left out.</li>
154<li><strong>Finder</strong>: open an org file from Finder, with <code class="verbatim">open file.org</code> in Terminal, or by dropping it on Orgstar's Dock icon. Orgstar registers as the default app for org files and as an alternative editor for plain text. Each file opens as a buffer.</li>
155<li><strong>Links</strong>: following a <code class="verbatim">file:</code> link or an ID link opens the target file; see <a href="09-links.html">Links</a>.</li>
156<li><strong>Doom ex command</strong>: <code class="verbatim">:e FILE</code> opens <code class="verbatim">FILE</code>, relative to the current file's folder; <code class="verbatim">~</code> is expanded. A file that doesn't exist is reported as <code class="verbatim">No file FILE</code>.</li>
157</ul>
158<p>A file opened from Finder or by a link does not have to be inside one of your folders. Such a file is edited and saved normally, but it isn't listed in the sidebar, isn't indexed for search or the agenda, and isn't watched for outside changes (Orgstar still merges outside changes when it saves; see <em>Saving</em> below).</p>
159<p>Orgstar has no Open Recent menu. Instead, it reopens the buffers that were open when you quit, in the same order, with the same file showing and each caret where you left it. Files that no longer exist are skipped.</p>
160<h3 id="files-that-aren-t-org">Files that aren't org</h3>
161<p>How a file opens depends on what it is:</p>
162<ul>
163<li><strong>Org files</strong> (<code class="verbatim">.org</code>, <code class="verbatim">.org_archive</code>) open in the editor with org editing.</li>
164<li><strong>Text files</strong> 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 <code class="verbatim">Not an org file</code>, and the outline pane shows "No outline" when you turn it on. Files in these languages get syntax highlighting: shell (<code class="verbatim">.sh</code>, <code class="verbatim">.bash</code>, <code class="verbatim">.zsh</code>, <code class="verbatim">.zshrc</code>, <code class="verbatim">.bashrc</code>, <code class="verbatim">.profile</code>), Python, Emacs Lisp, C, C++, R, JavaScript, Java, Scheme, Clojure, Haskell, Rust, Go, Ruby, JSON, YAML, TOML and Lua.</li>
165<li><strong>Everything else</strong> (images, PDFs, audio, video, archives, binary files) shows a Quick Look preview in place of the editor, with <code class="verbatim">Open with Default App</code> and <code class="verbatim">Show in Finder</code> buttons below it. The preview is not a buffer.</li>
166</ul>
167<p>Text files from Finder use Orgstar only if you choose it with Open With, since Orgstar is not their default app.</p>
168<h2 id="buffers">Buffers</h2>
169<p>Each open file is a buffer, as in Emacs. A buffer keeps its text, caret, folds, undo history and unsaved edits while another buffer is showing. Opening a file that already has a buffer shows that buffer. Two paths to the same file (through a symbolic link, for example) share one buffer, as <code class="verbatim">find-buffer-visiting</code> does.</p>
170<p>A new buffer is placed after the current one in the buffer order. Next and Previous Buffer follow that order and wrap around. Switch to Buffer and Last Buffer follow the order in which you last showed buffers.</p>
171<h3 id="buffer-commands">Buffer commands</h3>
172<table>
173<thead>
174<tr><th>Command</th><th>Menu, or palette</th><th>Mac</th><th>Emacs preset</th><th>Doom (normal state)</th></tr>
175</thead>
176<tbody>
177<tr><td>Switch to Buffer…</td><td>Window ▸ Switch to Buffer…</td><td></td><td><code class="verbatim">C-x b</code>, <code class="verbatim">C-x C-b</code></td><td><code class="verbatim">SPC b b</code>, <code class="verbatim">SPC b B</code>, <code class="verbatim">SPC ,</code>, <code class="verbatim">:b</code>, <code class="verbatim">:ls</code></td></tr>
178<tr><td>Next Buffer</td><td>Window ▸ Next Buffer</td><td><code class="verbatim">⇧⌘]</code>, <code class="verbatim">⌃Tab</code></td><td><code class="verbatim">⇧⌘]</code>, <code class="verbatim">C-x &lt;right&gt;</code></td><td><code class="verbatim">SPC b n</code>, <code class="verbatim">SPC b ]</code>, <code class="verbatim">] b</code>, <code class="verbatim">:bn</code></td></tr>
179<tr><td>Previous Buffer</td><td>Window ▸ Previous Buffer</td><td><code class="verbatim">⇧⌘[</code>, <code class="verbatim">⌃⇧Tab</code></td><td><code class="verbatim">⇧⌘[</code>, <code class="verbatim">C-x &lt;left&gt;</code></td><td><code class="verbatim">SPC b p</code>, <code class="verbatim">SPC b [</code>, <code class="verbatim">[ b</code>, <code class="verbatim">:bp</code></td></tr>
180<tr><td>Last Buffer</td><td>palette</td><td></td><td></td><td><code class="verbatim">SPC `</code></td></tr>
181<tr><td>Close Buffer</td><td>File ▸ Close Buffer</td><td><code class="verbatim">⌘W</code></td><td><code class="verbatim">⌘W</code>, <code class="verbatim">C-x k</code></td><td><code class="verbatim">SPC b k</code>, <code class="verbatim">SPC b d</code>, <code class="verbatim">:bd</code></td></tr>
182<tr><td>Close Other Buffers</td><td>palette</td><td></td><td></td><td><code class="verbatim">SPC b O</code></td></tr>
183<tr><td>Close All Buffers</td><td>palette</td><td></td><td></td><td><code class="verbatim">SPC b K</code></td></tr>
184</tbody>
185</table>
186<p>Menu shortcuts (<code class="verbatim">⇧⌘]</code>, <code class="verbatim">⌘W</code> and the others) work in every preset. The Doom preset also has the Emacs preset's <code class="verbatim">C-x</code> keys in every state. The Mac preset's <code class="verbatim">⌃Tab</code> and <code class="verbatim">⌃⇧Tab</code> are in addition to the menu shortcuts.</p>
187<p>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, <code class="verbatim">Tab</code> to complete the top choice, <code class="verbatim">Return</code> to switch, <code class="verbatim">Escape</code> to cancel.</p>
188<p>Close Buffer closes the current buffer and shows the buffer you showed before it. With no buffer open, <code class="verbatim">⌘W</code> closes the window. In other windows (Agenda, Board and so on) <code class="verbatim">⌘W</code> closes that window. File ▸ Close Window (<code class="verbatim">⇧⌘W</code>) closes the window in front.</p>
189<p>When you close buffers with unsaved edits, what happens depends on the save mode (see <em>Saving</em> below): in automatic mode they are saved first; in explicit mode Orgstar asks <code class="verbatim">Save</code>, <code class="verbatim">Don't Save</code> or <code class="verbatim">Cancel</code> (<code class="verbatim">Save All</code> for several files). A buffer whose save fails or conflicts stays open.</p>
190<h3 id="buffer-names">Buffer names</h3>
191<p>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 <code class="verbatim">post-forward-angle-brackets</code>:</p>
192<pre><code class="language-text">notes.org&lt;work&gt;
193notes.org&lt;home&gt;
194notes.org&lt;archive/2024&gt;</code></pre>
195<p>These names show in the window title, the tab bar and Switch to Buffer.</p>
196<h3 id="the-tab-bar">The tab bar</h3>
197<p>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 <code class="verbatim">tab-bar</code> in <code class="verbatim">config.toml</code>.</p>
198<ul>
199<li>Click a tab to show its buffer. Hover to see the file's full path.</li>
200<li>Click <code class="verbatim">×</code> to close a buffer. A dot replaces the <code class="verbatim">×</code> while the buffer has unsaved edits; clicking it also closes the buffer, with the same unsaved-changes handling as Close Buffer.</li>
201</ul>
202<h2 id="searching-your-notes">Searching your notes</h2>
203<p>The search field in the toolbar searches every org file in your folders. Click it or choose Edit ▸ Search Notes (<code class="verbatim">⇧⌘F</code>; <code class="verbatim">SPC /</code> or <code class="verbatim">SPC s p</code> in Doom normal state) and type.</p>
204<p>While the field holds text, the outline pane shows the results in place of the outline. Each result is a heading, with its file's name below it. Click a result to open the file at that heading. Clear the field to get the outline back.</p>
205<p>How matching works:</p>
206<ul>
207<li>Orgstar searches heading titles and the text under each heading, in <code class="verbatim">.org</code> and <code class="verbatim">.org_archive</code> files. Text before the first heading and files that aren't org are not searched. Syncthing conflict copies are not searched.</li>
208<li>Each word you type matches words that start with it: <code class="verbatim">proj</code> finds <code class="verbatim">project</code> and <code class="verbatim">projection</code>.</li>
209<li>Every word must match within the same heading.</li>
210<li>Up to 50 results show, best matches first.</li>
211<li>Open buffers with unsaved edits are searched as they are in the buffer, not as they are on disk.</li>
212</ul>
213<p>To find text inside the open file, use Edit ▸ Find (see <a href="02-the-editor.html">The editor</a>).</p>
214<h2 id="the-outline-pane">The outline pane</h2>
215<p>The outline pane lists the headings of the open org file, indented by level. Headings without a title show as <code class="verbatim">(untitled)</code>. Click a heading to move the caret to it; folded headings around it unfold. A file without headings shows "No headings"; a file that isn't org shows "No outline".</p>
216<p>The outline follows your edits after a short pause in typing.</p>
217<h3 id="backlinks">Backlinks</h3>
218<p>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) (<code class="verbatim">Links to this file</code>) and to the heading at the caret (<code class="verbatim">Links to</code> 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 <a href="09-links.html">Links</a>.</p>
219<h3 id="inspector">Inspector</h3>
220<p>View ▸ Show or Hide Columns and Clock (<code class="verbatim">⌥⌘I</code>) opens a pane on the right with column view and clocked time for the file or the current subtree. See <a href="04-outlines.html">Outlines</a> and <a href="06-dates-and-clocking.html">Dates and clocking</a>.</p>
221<h2 id="saving">Saving</h2>
222<p>Settings ▸ General ▸ Save files has two modes; the <code class="verbatim">config.toml</code> setting is <code class="verbatim">save</code> in <code class="verbatim">[orgstar]</code>.</p>
223<ul>
224<li><strong>Automatically, when typing stops</strong> (<code class="verbatim">automatic</code>, the default). Each buffer saves one second after its last change, including buffers that are not showing. Quitting and closing buffers save without asking.</li>
225<li><strong>Only with File ▸ Save (⌘S)</strong> (<code class="verbatim">explicit</code>). Nothing is written until you save. Closing a buffer or quitting with unsaved edits asks first.</li>
226</ul>
227<table>
228<thead>
229<tr><th>Command</th><th>Menu</th><th>Shortcut</th><th>Emacs preset</th><th>Doom</th></tr>
230</thead>
231<tbody>
232<tr><td>Save</td><td>File ▸ Save</td><td><code class="verbatim">⌘S</code></td><td><code class="verbatim">C-x C-s</code></td><td><code class="verbatim">SPC f s</code>, <code class="verbatim">SPC b s</code>, <code class="verbatim">:w</code>; <code class="verbatim">:wq</code> and <code class="verbatim">:x</code> save and close the window</td></tr>
233<tr><td>Save All</td><td>File ▸ Save All</td><td><code class="verbatim">⌥⌘S</code></td><td><code class="verbatim">C-x s</code></td><td><code class="verbatim">SPC b S</code></td></tr>
234</tbody>
235</table>
236<p>Save is disabled for a read-only file. Save All is disabled when nothing is unsaved.</p>
237<p>The modeline shows a dot while the current buffer has unsaved edits. Buffers with unsaved edits show a dot in the tab bar.</p>
238<h3 id="how-a-save-works">How a save works</h3>
239<p>Orgstar does not assume it is the only program writing your files. Emacs, Syncthing, iCloud and Git may change them too. Each save:</p>
240<ol>
241<li>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 <em>External changes</em> below). If they conflict with yours, nothing is written and the buffer has a conflict.</li>
242<li>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.</li>
243<li>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.</li>
244</ol>
245<p>Every version a save displaces goes to recovery first (see <em>Recovery versions</em> below). Reads and writes go through macOS file coordination, so iCloud and other coordinating programs see a consistent file.</p>
246<p>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.</p>
247<h2 id="external-changes">External changes</h2>
248<p>Orgstar watches the files in your folders. When a file with an open buffer changes on disk:</p>
249<ul>
250<li>If the buffer has no unsaved edits, it reloads. The caret and folds stay where they were, mapped through the change.</li>
251<li>If the buffer has unsaved edits, Orgstar merges the change into the buffer line by line, against the version both started from. Lines changed on one side take that side; lines changed the same way on both sides are taken once. The merged buffer still has unsaved edits and saves as usual.</li>
252<li>If both sides changed the same lines differently, the buffer has a conflict.</li>
253</ul>
254<p>Reloading or merging clears the buffer's undo history.</p>
255<p>If an open file is deleted on disk, its buffer stays open with its text. Saving it writes the file again.</p>
256<p>To throw away your unsaved edits and load the file as it is on disk, run Revert to File on Disk from the palette (<code class="verbatim">:e</code> in Doom). Your edits go to recovery.</p>
257<h3 id="conflicts">Conflicts</h3>
258<p>When a buffer conflicts with its file, automatic saving stops for that buffer, the <code class="verbatim">Conflict</code> button appears in the toolbar, and the conflict sheet opens. The sheet shows the differences: lines marked <code class="verbatim">-</code> are on disk, lines marked <code class="verbatim">+</code> are in your version, with three lines of context around each change. Choose:</p>
259<table>
260<thead>
261<tr><th>Button</th><th>What it does</th></tr>
262</thead>
263<tbody>
264<tr><td>Keep Mine</td><td>Writes your version over the file. The disk version goes to recovery. This is the default button.</td></tr>
265<tr><td>Use Disk Version</td><td>Loads the file as it is on disk. Your version goes to recovery.</td></tr>
266<tr><td>Merge with Markers</td><td>Puts both sets of changes in the buffer, as <code class="verbatim">git merge</code> leaves a conflict: non-conflicting changes merged, conflicting lines between markers. Your version as it was goes to recovery.</td></tr>
267<tr><td>Decide Later</td><td>Closes the sheet. The conflict stays; click <code class="verbatim">Conflict</code> in the toolbar to reopen it.</td></tr>
268</tbody>
269</table>
270<p>After Merge with Markers the buffer holds blocks like this, which you edit and save:</p>
271<pre><code class="language-text">&lt;&lt;&lt;&lt;&lt;&lt;&lt; yours
272- [ ] Call the plumber on Monday
273=======
274- [X] Call the plumber
275&gt;&gt;&gt;&gt;&gt;&gt;&gt; disk</code></pre>
276<p>While a conflict is unresolved, saving that buffer does nothing except reopen the sheet.</p>
277<h3 id="syncthing-conflict-copies">Syncthing conflict copies</h3>
278<p>When two devices change a file before Syncthing syncs them, Syncthing keeps one version as a conflict copy beside the file, named like <code class="verbatim">notes.sync-conflict-20260301-142233-ABCDEF7.org</code>. 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.</p>
279<p>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 <code class="verbatim">-</code> are in the file (as the buffer holds it) and lines marked <code class="verbatim">+</code> are in the copy. Then choose:</p>
280<table>
281<thead>
282<tr><th>Button</th><th>What it does</th></tr>
283</thead>
284<tbody>
285<tr><td>Keep File</td><td>Leaves the buffer as it is.</td></tr>
286<tr><td>Use Copy</td><td>Replaces the buffer's text with the copy's.</td></tr>
287<tr><td>Merge with Markers</td><td>Puts every difference between the buffer and the copy between conflict markers, labelled with the two file names. There is no common base to merge against, so every difference is marked.</td></tr>
288</tbody>
289</table>
290<p>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.</p>
291<h3 id="recovery-versions">Recovery versions</h3>
292<p>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 <code class="verbatim">~/Library/Application Support/Orgstar/Recovery</code>.</p>
293<p>Run Recovery Versions… from the palette to see the open file's versions, newest first, each with its date and why it was kept:</p>
294<table>
295<thead>
296<tr><th>Label</th><th>Meaning</th></tr>
297</thead>
298<tbody>
299<tr><td>Your version, replaced</td><td>Your buffer, before it was replaced</td></tr>
300<tr><td>Disk version, replaced</td><td>The file on disk, before Orgstar wrote over it</td></tr>
301<tr><td>Sync conflict copy</td><td>A Syncthing conflict copy you resolved</td></tr>
302</tbody>
303</table>
304<p>Select a version to see how it differs from the buffer (<code class="verbatim">-</code> in the buffer, <code class="verbatim">+</code> in the kept version). <code class="verbatim">Restore</code> puts the kept version's text in the buffer as one edit, which undo reverses; the buffer as it was goes to recovery first. <code class="verbatim">Show in Finder</code> reveals the kept file.</p>
305<h3 id="icloud">iCloud</h3>
306<p>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.</p>
307<h2 id="encodings-and-line-endings">Encodings and line endings</h2>
308<p>Orgstar edits UTF-8 files, with or without a byte order mark.</p>
309<ul>
310<li>A file that is not valid UTF-8 opens read-only. Its text shows with replacement characters where bytes don't decode, the window subtitle reads <code class="verbatim">Read-only: not UTF-8</code>, the modeline shows <code class="verbatim">Read-only</code>, and commands that would change it report <code class="verbatim">This file is read-only.</code> Orgstar never writes such a file, and refiling or archiving into it is refused.</li>
311<li>A file with a UTF-8 byte order mark keeps it when saved; the modeline shows <code class="verbatim">BOM</code>.</li>
312<li>A file containing CRLF line endings shows <code class="verbatim">CRLF</code> in the modeline. Existing line endings are kept.</li>
313</ul>
314<p>Orgstar does not convert between encodings or line endings.</p>
315<h2 id="on-ios">On iOS</h2>
316<p>The iOS app adds folders from its Folders screen and lists only org files there. Conflicts, Syncthing copies and recovery versions are in the editor's menu. Files are watched through file presenters rather than FSEvents. See <a href="14-ios.html">iOS</a>.</p>
317</main>
318<footer class="site">
319Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
320</footer>
321</body>
322</html>