Northern Commander

The settings file

Every setting is in one JSON file, ~/.northern-commander/settings.json. The settings screen and the file are two views of the same settings: use the file to read them all at once, to change them by hand, or to copy them to another Mac.

Every setting is written out, whether or not you changed it.

Opening it

Open settings.json, on the settings screen — Settings…, or ⌘, — closes the screen and opens the file in the built-in editor, asking first where you changed something on the screen and have not applied it. Any other editor works as well. The line under each setting on the screen ends with its name in the file.

What each setting does, its default and the values it takes are under Settings.

What is in it

  • Every setting, whether or not you changed it. The file is where you find out what can be set, so one listing only your changes would tell you nothing.
  • In a fixed order, the order of the settings screen’s pages, so a file edited over months still reads the way it first did.
  • fileTypes, your own kinds of file — see File types in settings.json. The kinds that ship are not in it.
  • Anything else you put in it — $schema, or a setting only another version knows — kept after the settings.

A flag is true or false, a number is a whole number, and a choice is one of its words exactly as the settings screen shows it — "as they change", case and all.

Editing it by hand

The file is read when the application starts, so a change made by hand counts from the next start. While the application runs:

  • A save writes only what that run changed. A setting you edited by hand and the application did not change keeps what you wrote.
  • A setting changed in the application as well as by hand ends up as the application has it.

When it is written

A change is in force the moment it is set — by a key at once, on the settings screen and the File types screen when you choose OK or Apply. Write settings decides only when the file catches up:

saveSettings The file is written
as they change — the default As each change is set: by OK or Apply on the settings screen and the File types screen, by Open with… and Always color … like this, and by a key that changes a setting, such as the text size or hidden files
on quit As the application quits
when asked When you ask: Save settings in the Options menu
  • Save settings writes the settings whatever Write settings says. OK and Apply put what you changed in force, and leave the file to Write settings.
  • A change to Write settings itself is written at once, whatever it is changing to.
  • The file is written beside itself and then moved into place, so a save that is cut short leaves the settings that were there.

A value it cannot use

A mistake costs that one setting and nothing around it; the log says what was refused.

  • A value of the wrong kind — text where a number goes, a word that is not one of the choices, a number outside its range — leaves that setting at its default.
  • null is the same as leaving the setting out: it stays at its default.
  • fileTypes, the one list, keeps what it can: a kind of file that cannot be read is left out and the others still work — see mistakes.
  • A key this version does not know is kept, and written back after the settings, so a newer or older version sharing the file does not lose its own.

Checking it in an editor

The file’s shape is published as a JSON schema, which names every setting with what it does, its default and the values it takes:

https://northerncommander.com/schemas/settings.schema.json

For your editor to check the file and complete it as you type, add a $schema line:

{
  "$schema": "https://northerncommander.com/schemas/settings.schema.json",
  "fontSize": 15
}

The application keeps the line, and moves it to the end of the file the next time it writes. Or tie the schema to the file in your editor’s own settings instead — in Visual Studio Code, under json.schemas.

A fresh start

Quit, delete settings.json, and start again: every setting is at its default, and a new file is written the next time the settings are. Deleting it while the application runs does not reset anything — the application still holds the settings, and writes them back the next time it writes.

A backup can hold the settings, to put back later.