Documents and projects
Table of Contents
A window holds several documents. Opening a file (Ctrl+O, the File
menu, a file link, or Finder) shows it in the same window. The open
files are listed on the left; ui.open_files puts them at the top as
tabs or hides them, and Ctrl+Shift+E shows or hides the list. A click
shows a document. Ctrl+Tab and Ctrl+PageDown go to the next one,
Ctrl+Shift+Tab and Ctrl+PageUp to the previous one, Ctrl+Alt+O lists
them by name, Ctrl+Alt+R lists the files you opened recently, and
Ctrl+W closes the document, asking first when it has unsaved changes.
A project is a folder in your project list. Add Project (SPC p a
with Vim keys) asks for its path, the document's folder offered and
its folders listed (Tab completes a name, the arrows choose one), and
Add Project Folder… (Project menu) chooses one in a dialog. Only the
folders you add are projects. Toggle Adding Projects Automatically
(Project menu), or the Projects row of the settings panel, makes a
folder under version control (Git, Mercurial, Subversion), or with a
.projectile file or a .kalem folder (where a project's own settings
live), join the list by itself when you open one of its files, as in
Projectile (projects.auto_add = true). A folder a plugin's layer
serves (a Logseq graph by its logseq/config.edn, an Obsidian vault by
its .obsidian/) is a project by its nature, and the plugin reads only
projects' folders: opening one of its notes outside the projects offers
to add it, once a session (Enter adds it, Escape leaves it), or adds it
at once with projects.auto_add. Nothing is written into the
folder: the list and the recent files are kept in projects.toml
beside settings.toml.
The document you are in decides the current project: Ctrl+P and Search in Project work on it at once, and Switch Project lists it first. Files are listed under their project's name, files outside every project after them, and the status bar shows the document's project.
| Keys | Command |
|---|---|
| Ctrl+Alt+P | Switch Project: its folder the first time, then its last file |
| Ctrl+P | Find File in Project, recent files first |
| Ctrl+Shift+F | Search in Project; Alt+C case, Alt+W words, Alt+R regular expression |
| Recent Files in Project, Remove Project, Rename Project (palette) |
In the palette: Switch Document in Project lists the project's open
documents, Save Project Documents and Close Project Documents save
or close them (those with unsaved changes stay open), and Refresh
Project Files walks the folder again for files added or removed
outside Kalem. The file list follows ripgrep's ignore rules,
.gitignore and .ignore files with or without a Git repository, and
never lists .git itself or binary files.
1. The folder tree
The folder tree is hidden at first, as the file manager lists a folder
(File Manager, SPC o - with Vim's keys). Toggle Folder Tree
shows or hides it, saving the setting ui.folder_tree, and Reveal in
Folder Tree shows it. When the document is in a project and the open
files are on the left, the project's folders and files are then listed
below them, folders first, with the same ignore rules. A click opens
or closes a folder or opens a file, and the document's file is marked.
Reveal in Folder Tree opens the folders down to the document's file.