docs/manual/guide/01-files-and-folders.org
313 lines · 25615 bytes
1#+TITLE: Files, folders and buffers
2#+DESCRIPTION: Adding folders, opening files, working with buffers, searching, saving, and how Orgstar handles changes made outside it.
3#+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.
4
5* The window
6
7Orgstar has one main window, titled with the name of the buffer it shows. From left to right it holds:
8
9- the *sidebar*, listing the folders you added and the files in them;
10- the *outline pane*, listing the headings of the open file, with the *backlinks pane* under it;
11- the *editor*, with the optional tab bar above it and the modeline and echo area below it;
12- the *inspector*, hidden by default, showing column view and clocked time.
13
14The toolbar holds a button that shows or hides the outline pane, a progress indicator while Orgstar indexes your folders, the running clock (see [[file:06-dates-and-clocking.org][Dates and clocking]]), a =Conflict= button when the open file has a conflict (see /Conflicts/ below), and the search field.
15
16The window title is the buffer name (see /Buffer names/ below). When the open file is not UTF-8, the subtitle reads =Read-only: not UTF-8=. The close button shows the unsaved-changes dot while any open buffer has unsaved edits.
17
18With 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 =⌘P=.
19
20The Agenda, Board, Clock Report and Capture windows are separate; they are covered in [[file:07-agenda.org][Agenda]], [[file:06-dates-and-clocking.org][Dates and clocking]] and [[file:08-capture.org][Capture]]. Closing the main window quits Orgstar when no other window is open.
21
22** Menus and the command palette
23
24Most 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.
25
26File ▸ 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.
27
28Several 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….
29
30** Showing and hiding panes
31
32| Menu item | Shortcut | Palette title |
33|------------------------------------------+----------+----------------------------------|
34| View ▸ Show or Hide Outline | =⌥⌘O= | Show or Hide Outline |
35| View ▸ Show or Hide Backlinks | | Show or Hide Backlinks |
36| View ▸ Show or Hide Columns and Clock | =⌥⌘I= | Show or Hide Columns and Clock |
37| View ▸ Show Tab Bar | | Show or Hide Tab Bar |
38
39The 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.
40
41Orgstar 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).
42
43* Folders
44
45Orgstar 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.
46
47** Adding a folder
48
49Choose 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.
50
51Orgstar 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.
52
53Orgstar keeps the list of folders, the index and recovery versions in =~/Library/Application Support/Orgstar=.
54
55** Removing a folder
56
57Click =−= 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.
58
59** What the sidebar lists
60
61Each 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.
62
63The sidebar lists every file in the folder, not only org files, with an icon for its kind:
64
65| Icon | File |
66|-----------------------+------------------------------------------------------------|
67| document | =.org= |
68| archive box | =.org_archive= |
69| orange warning sign | a Syncthing conflict copy (see /Syncthing conflict copies/ below) |
70| photo | an image |
71| rich document | a PDF |
72| play button | audio or video |
73| =</>= | source code or a script |
74| plain document | other text |
75| cloud with arrow | an iCloud file still downloading (see /iCloud/ below) |
76
77Some files are never listed or indexed:
78
79- Emacs backups (names ending in =~=), auto-save files (names starting with =#=) and lock files (=.#name=);
80- Syncthing's temporary files (=.syncthing.*=);
81- Orgstar's own temporary files (names containing =.orgstar-=);
82- =.DS_Store= and =.localized=;
83- 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=.
84
85Other 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 [[file:13-configuration.org][Configuration]].
86
87#+BEGIN_SRC toml
88[orgstar]
89show-hidden-files = true
90ignored-folders = ".git .hg node_modules build"
91#+END_SRC
92
93Only 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.
94
95** Creating, renaming and trashing files
96
97Right-click a file or folder in the sidebar for:
98
99- 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.
100- 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.
101- Show in Finder.
102- 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.
103
104Right-click a root's header for New File…, Expand or Collapse, Show in Finder and Remove from Sidebar….
105
106* Opening files
107
108Click a file in the sidebar to open it. Other ways:
109
110- *Quick Open*: File ▸ Quick Open… (=⌘P=; =C-x C-f= in the Emacs and Doom presets; =SPC SPC=, =SPC .= or =SPC f f= 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; =↑= and =↓=, or =C-p= and =C-n=, move the selection. Press =Return= to open the selected match or click any match; =Escape= closes the list. Syncthing conflict copies are left out.
111- *Finder*: open an org file from Finder, with =open file.org= 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.
112- *Links*: following a =file:= link or an ID link opens the target file; see [[file:09-links.org][Links]].
113- *Doom ex command*: =:e FILE= opens =FILE=, relative to the current file's folder; =~= is expanded. A file that doesn't exist is reported as =No file FILE=.
114
115A 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 /Saving/ below).
116
117Orgstar 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.
118
119** Files that aren't org
120
121How a file opens depends on what it is:
122
123- *Org files* (=.org=, =.org_archive=) open in the editor with org editing.
124- *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.
125- *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.
126
127Text files from Finder use Orgstar only if you choose it with Open With, since Orgstar is not their default app.
128
129* Buffers
130
131Each 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 =find-buffer-visiting= does.
132
133A 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.
134
135** Buffer commands
136
137| Command | Menu, or palette | Mac | Emacs preset | Doom (normal state) |
138|---------------------+----------------------------------+-------------------+------------------------------+-------------------------------------------|
139| Switch to Buffer… | Window ▸ Switch to Buffer… | | =C-x b=, =C-x C-b= | =SPC b b=, =SPC b B=, =SPC ,=, =:b=, =:ls= |
140| Next Buffer | Window ▸ Next Buffer | =⇧⌘]=, =⌃Tab= | =⇧⌘]=, =C-x <right>= | =SPC b n=, =SPC b ]=, =] b=, =:bn= |
141| Previous Buffer | Window ▸ Previous Buffer | =⇧⌘[=, =⌃⇧Tab= | =⇧⌘[=, =C-x <left>= | =SPC b p=, =SPC b [=, =[ b=, =:bp= |
142| Last Buffer | palette | | | =SPC `= |
143| Close Buffer | File ▸ Close Buffer | =⌘W= | =⌘W=, =C-x k= | =SPC b k=, =SPC b d=, =:bd= |
144| Close Other Buffers | palette | | | =SPC b O= |
145| Close All Buffers | palette | | | =SPC b K= |
146
147Menu 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.
148
149Switch 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.
150
151Close 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.
152
153When 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.
154
155** Buffer names
156
157A 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=:
158
159#+BEGIN_SRC text
160notes.org<work>
161notes.org<home>
162notes.org<archive/2024>
163#+END_SRC
164
165These names show in the window title, the tab bar and Switch to Buffer.
166
167** The tab bar
168
169View ▸ 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=.
170
171- Click a tab to show its buffer. Hover to see the file's full path.
172- 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.
173
174* Searching your notes
175
176The search field in the toolbar searches every org file in your folders. Click it or choose Edit ▸ Search Notes (=⇧⌘F=; =SPC /= or =SPC s p= in Doom normal state) and type.
177
178While 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.
179
180How matching works:
181
182- Orgstar searches heading titles and the text under each heading, in =.org= and =.org_archive= files. Text before the first heading and files that aren't org are not searched. Syncthing conflict copies are not searched.
183- Each word you type matches words that start with it: =proj= finds =project= and =projection=.
184- Every word must match within the same heading.
185- Up to 50 results show, best matches first.
186- Open buffers with unsaved edits are searched as they are in the buffer, not as they are on disk.
187
188To find text inside the open file, use Edit ▸ Find (see [[file:02-the-editor.org][The editor]]).
189
190* The outline pane
191
192The outline pane lists the headings of the open org file, indented by level. Headings without a title show as =(untitled)=. 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".
193
194The outline follows your edits after a short pause in typing.
195
196** Backlinks
197
198Under 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 [[file:09-links.org][Links]].
199
200** Inspector
201
202View ▸ 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 [[file:04-outlines.org][Outlines]] and [[file:06-dates-and-clocking.org][Dates and clocking]].
203
204* Saving
205
206Settings ▸ General ▸ Save files has two modes; the =config.toml= setting is =save= in =[orgstar]=.
207
208- *Automatically, when typing stops* (=automatic=, the default). Each buffer saves one second after its last change, including buffers that are not showing. Quitting and closing buffers save without asking.
209- *Only with File ▸ Save (⌘S)* (=explicit=). Nothing is written until you save. Closing a buffer or quitting with unsaved edits asks first.
210
211| Command | Menu | Shortcut | Emacs preset | Doom |
212|----------+----------------------+----------+--------------+--------------------------------------|
213| Save | File ▸ Save | =⌘S= | =C-x C-s= | =SPC f s=, =SPC b s=, =:w=; =:wq= and =:x= save and close the window |
214| Save All | File ▸ Save All | =⌥⌘S= | =C-x s= | =SPC b S= |
215
216Save is disabled for a read-only file. Save All is disabled when nothing is unsaved.
217
218The modeline shows a dot while the current buffer has unsaved edits. Buffers with unsaved edits show a dot in the tab bar.
219
220** How a save works
221
222Orgstar does not assume it is the only program writing your files. Emacs, Syncthing, iCloud and Git may change them too. Each save:
223
2241. 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.
2252. 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.
2263. 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.
227
228Every 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.
229
230A 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.
231
232* External changes
233
234Orgstar watches the files in your folders. When a file with an open buffer changes on disk:
235
236- If the buffer has no unsaved edits, it reloads. The caret and folds stay where they were, mapped through the change.
237- 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.
238- If both sides changed the same lines differently, the buffer has a conflict.
239
240Reloading or merging clears the buffer's undo history.
241
242If an open file is deleted on disk, its buffer stays open with its text. Saving it writes the file again.
243
244To throw away your unsaved edits and load the file as it is on disk, run Revert to File on Disk from the palette (=:e= in Doom). Your edits go to recovery.
245
246** Conflicts
247
248When 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:
249
250| Button | What it does |
251|--------------------+------------------------------------------------------------------------------------------------------------------|
252| Keep Mine | Writes your version over the file. The disk version goes to recovery. This is the default button. |
253| Use Disk Version | Loads the file as it is on disk. Your version goes to recovery. |
254| Merge with Markers | Puts both sets of changes in the buffer, as =git merge= leaves a conflict: non-conflicting changes merged, conflicting lines between markers. Your version as it was goes to recovery. |
255| Decide Later | Closes the sheet. The conflict stays; click =Conflict= in the toolbar to reopen it. |
256
257After Merge with Markers the buffer holds blocks like this, which you edit and save:
258
259#+BEGIN_SRC text
260<<<<<<< yours
261- [ ] Call the plumber on Monday
262=======
263- [X] Call the plumber
264>>>>>>> disk
265#+END_SRC
266
267While a conflict is unresolved, saving that buffer does nothing except reopen the sheet.
268
269** Syncthing conflict copies
270
271When 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.
272
273When 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:
274
275| Button | What it does |
276|--------------------+------------------------------------------------------------------------------------|
277| Keep File | Leaves the buffer as it is. |
278| Use Copy | Replaces the buffer's text with the copy's. |
279| Merge with Markers | 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. |
280
281Each 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.
282
283** Recovery versions
284
285Whenever 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=.
286
287Run Recovery Versions… from the palette to see the open file's versions, newest first, each with its date and why it was kept:
288
289| Label | Meaning |
290|-------------------------+-------------------------------------------------|
291| Your version, replaced | Your buffer, before it was replaced |
292| Disk version, replaced | The file on disk, before Orgstar wrote over it |
293| Sync conflict copy | A Syncthing conflict copy you resolved |
294
295Select 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.
296
297** iCloud
298
299Files 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.
300
301* Encodings and line endings
302
303Orgstar edits UTF-8 files, with or without a byte order mark.
304
305- 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 =Read-only: not UTF-8=, the modeline shows =Read-only=, and commands that would change it report =This file is read-only.= Orgstar never writes such a file, and refiling or archiving into it is refused.
306- A file with a UTF-8 byte order mark keeps it when saved; the modeline shows =BOM=.
307- A file containing CRLF line endings shows =CRLF= in the modeline. Existing line endings are kept.
308
309Orgstar does not convert between encodings or line endings.
310
311* On iOS
312
313The 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 [[file:14-ios.org][iOS]].