Customization Sync Documentation

[etherealite]

Thanks to @vrtmrz for making Self-hosted LiveSync and also for those participating in its development.
@vrtmrz, Self-hosted LiveSyncを作ったくれてありがとうございます。プラグイン発達参加者の皆さんにも感謝します。

This is incomplete for the time being, but I will add more to it soon.

I'd like to help clearify the UI for customization sync and how it works in general. I hope people might find this usefull and be willing to extend or ammend what I've laid out so far.

An Overview of Customization Sync

The customization sync feature is a way to sync Obsidian configuration information contained with a vault. By introducing the ability to pin the state of select files to a particular device, it allows for the controlled synchronization of Obsidian core settings, plugins and plugin settings. Such file state can be shared between devices where it is needed and be excluded when it is not.

Motivation and Differences from the Regular Sync

Customization sync differs from the core functionality of Self-Hosted LiveSync where files are treated the same across all devices. Doing a one to one sync of all files contained within the configuration folder would in many cases, disrupt the operation of the vault across different devices. customization sync provides a way to keep the configuration files that are invariant between devices in sync while those that are not can be left untouched.

Files Which Customization Sync Can Manage

The specific files that customization sync works with fall within two main areas of concern. The first are is are those files related to the core functionality of obsidian. These are files that contain the main app config, core plugin configuration and styling of the interface. The second type of files are those of the community plugins that are copied into the vault upon their installation.

Application Files

The files related to the core that can be tracked are the json configuration files behind the core plugins, themes including any and all of their subsequent files and finally all the CSS files within the snippets folder. The core plugins have limited tracking where only the json files are tracked. The actual implementations of the core plugins are not contained within a vault so they are not tracked.

Files tracked

Vault	Files
vault/
	*.json
	themes/*
	snippets/*

Community Plugin Files

Community plugin files have both their json configuration files as well as their implementation managed. granted they adhere to the . This means that within any given plugin directory all three of styles.css, manifest.json and styles.css

Files Tracked

Vault	Plugin	Files
vault/plugins/
	plugin-a/
		manifest.json
		main.js
		styles.css
	plugin-b/
		manifest.json
		main.js
		styles.css
	...	...

To see how customization sync classifies configuration files, take a look at the getFileCategory function in the source code.

Device Pinning

In order for configuration files to be selectively included or excluded from being synced, each device that holds the vault you are replicating is given a unique name. Before enabling customization sync, you provide the ui with a name for your device in the Device Name field of the settings panel. After creating the device name you can then activate customization sync by using the Enable customization sync toggle.

Assign your device a name here, ensuring that it is unique accross all your devices.

After creating a name for each of your devices, each will push a set of their own versions of the configuration file state to the remote database. This is stored outside the realm of the vault itself and is more or less sent only to the remote database. You will later have the option of copying these files between devices using the customization sync dialogue.

Managing Configuration files

Determining which configuration files to copy from the remote sources and when to do is accomplished through the customization sync dialogue window. Clicking the Open button at the bottom of the screen where the device name is entered will open the dialogue window. Once open, all actions against files and the remote database are performed using the five buttons at the top of the window.

Generating a List of Files to Inspect for Differences

To build the list of files from which to operate on, press the Scan changes button. The Sync Once and Refresh buttons are more granular than scan changes button but all are used for the generation of a list of files that can be used to copy file state from remote devices to your local vault. The sync once button will simply perform a vault wide replication as livesync normally does as its day to day core function. Once fresh data containing the different file pins has been fetched, one can then press the refresh button to generate a new list of comparison between your vault local state and the pinned remotes.

Examining the List of File States

Within the dialog there is a list of both application files and community plugin files available, each of which is being tracked by livesync across all devices. In the right hand column there will be a select menu with a single dash (-) as the default selected item for each file tacked by customization sync. Opening the menu will display the pins for your other device names, where after selecting one a comparison between the file on your local vault will be made with the pin that was chosen. It's important to note that no immediate changes will be made to the local vault by selecting different pins for each file.

Phone pinned version is selected and is newer but the same as the local vault.

Interpreting the Differences Between Files

The phone pinned version of this file is older than local vault file version

When there are no changes to be made, the third column of a file in the list of file states is empty. In the case where the local vault's version of a file is the same of that to witch it is being compared

changes will only be applied when apply all button is

All Action Buttons

• Scan changes - This is the equivelent of hitting the Sync once button and then the Refresh button. [#TODO not sure how files set to Automatic behave with this button.
• Sync once - Perform a one shot sync, also known as the replicate action. [#TODO Same as with Scan changes I'm not sure how Automatic mode works with it.]
• Refresh - Inspect the remote list of files pinned to other devices and compare to the ones in the local vault.
• Select All Shiny - Batch select all local configuration files to be overwritten by the latest version regardless of source device.
• Apply All - Synchronize the local vault's configuration files with the version pins that have been selected.

[alx-xlx]

Shouldn't all of the sync happen automatically ? What's the point of calling it sync then ?

anyways, Once I "Apply All" I am presented with a dialogue asking for "Fetch" "Custom" etc.. What to do there ?

[nicksmith53]

For the sync modes:

• The default Selective means use Customization Sync, which is manual. You can enable notification for changes but you have to go into this menu and to hit the select shiny and apply buttons by yourself
• Automatic just hands those files back to the hidden file sync system to deal with them
• And Ignore completely disables syncing that file in both systems

see #278 (comment)