Public release for the Obsidian Sync Tool

This is a prototype backup/sync utility intended for use with Obsidian to sync and/or backup vaults either to enable portability between devices (without cloud sync), serve as a backup mechanism and additionally perform simple sync operations. Released under a MIT license.

The Obsidian Sync Tool is able to perform various operations depending on selected options, they include:

Obsidian sync tool usage: ./obsidian_sync.sh [OPTIONS]
Required:
  -l, --local-vault PATH      Set local vault path
  -o, --obsidian-runtime PATH Set the full path to Obsidian application; .appimage etc.
Optional:
  -b, --backup-dir PATH       Set backup directory path (archive only)
  -n, --network-share PATH    Set network share path
  -a, --rsync-args ARRAY      Passs additional arguments to rsync such as: --dry-run to test changes (network-share must be valid)
  --backup-mechanism STR      Backup method: archive, git or both
  -g, --git-ops ARRAY         Perform additional git operations: pull, push (git only)
  -p, --periodic-sync BOOL    Enable period network sync uses selected backup-mechanism
  -r, --periodic-backup BOOL  Enable additional backup copy before period network sync
  -m, --max-backups NUM       Set maximum number of backups (archive only)
  -i, --interval SECONDS      Set sync interval in seconds (default 150s)
  -h, --help                  Display this help message

These are best understood with example:

Examples

These are but a few examples on what you can do with this utility but they cover the 3 backup methods supported.

Utilising a Git repository as the backup source

The options may look like:

./obsidian_sync.sh --local-vault "/home/user/vaults/test" --obsidian-runtime "/home/user/AppImages/gearlever_obsidian.appimage" --backup-mechanism "git" --git-ops "pull" --git-ops "push"

When ran this will use the local repository inside the vault to store commits representing backups; it flows as follows:

• On open it performs a “opening” commit on any changes.
• Then attempts to fetch and pull any changes.
• Then launches Obsidian with the selected vault and track the PID.
• Once Obsidian closes it performs a “closing” commit and push the changes to a remote (if a remote is set not which is not set by this utility).

If we omit the --git-ops "pull" --git-ops "push" args; the flow changes slightly:

• On open runs a backup (commit) on any changes.
• Then launches Obsidian with the selected vault and track the PID.
• Once Obsidian closes it performs a “closing” commit.

Utilising archives as the backup source

The options may look like:

./obsidian_sync.sh --local-vault "/home/user/vaults/test" --obsidian-runtime "/home/user/AppImages/gearlever_obsidian.appimage" --backup-mechanism "archive" --backup-dir "/home/user/backup_vaults/"

When ran this will use the local vault to create archives from and then store at the backup location; it flows as follows:

• On run create a backup archive (tar.gz) on the vault path storing at the backup path.
• Then launches Obsidian with the selected vault and track the PID.
• Once Obsidian closes it creates a “closing” backup archive on the vault path storing at the backup path

Utilise both backup sources

./obsidian_sync.sh --local-vault "/home/user/vaults/test" --obsidian-runtime "/home/user/AppImages/gearlever_obsidian.appimage" --backup-mechanism "both" --backup-dir "/home/user/backup_vaults/" --git-ops "pull" --git-ops "push"

When ran this will use the local repository inside the vault to store commits representing backups as well as creating archives from the vault and storing them at the backup location; it flows as follows:

• On open:
• it performs a “opening” commit on any changes.
• it creates a backup archive (tar.gz) on the vault path storing at the backup path
• Then attempts to fetch and pull any changes.
• Then launches Obsidian with the selected vault and track the PID.
• Once Obsidian closes:
• it performs a “closing” commit and push.
• it creates a “closing” backup archive on the vault path storing at the backup path

Rsync support

This maybe useful if you want to sync any vaults to a remote source like a network share; support additional optional rsync arguments:

./obsidian_sync.sh --local-vault "/home/user/vaults/test" --obsidian-runtime "/home/user/AppImages/gearlever_obsidian.appimage" --network-share "/some/network/share" --rsync-args "--dry-run" --rsync-args "--exclude .git"

When ran this will use the local vault to create archives from and then store at the backup location; it flows as follows:

• On run create a backup archive (tar.gz) on the vault path storing at the backup path.
• Attempts to sync from remote > local:
• The most recent backup copies are stored in a folder inside the backup path suffixed with .bk.
• Only newer files are retrieved.
• Then launches Obsidian with the selected vault and track the PID.
• Once Obsidian closes it creates a “closing” backup archive on the vault path storing at the backup path
• Attempts to sync from local > remote:
• The most recent backup copies are stored in a folder inside the backup path suffixed with .bk.
• Only newer files are sent.

Period sync/backup support

Similar to the Rsync example above only when Obsidian is open it will periodically perform the sync (to network) and backup depending on the runtime options.

./obsidian_sync.sh --local-vault "/home/user/vaults/test" --obsidian-runtime "/home/user/AppImages/gearlever_obsidian.appimage" --network-share "/some/network/share" --rsync-args "--dry-run" --rsync-args "--exclude .git" --periodic-sync true --periodic-backup true

Combine them all

You can also combine them all in to a monstrous command:

./obsidian_sync.sh --local-vault "/home/user/vaults/test" --obsidian-runtime "/home/user/AppImages/gearlever_obsidian.appimage" --backup-mechanism "both" --backup-dir "/home/user/backup_vaults/" --git-ops "pull" --git-ops "push" --network-share "/some/network/share" --rsync-args "--dry-run" --rsync-args "--exclude .git" --periodic-sync true --periodic-backup true

When ran it peforms all the operations from the 4 examples above.

GNOME support

You can generate a GNOME integration in the form of a launcher: oddsidian.desktop. this will use the options supplied minue the install-gnome arg as the Exec script in the .desktop file:

./obsidian_sync.sh --local-vault "/home/user/vaults/test" --obsidian-runtime "/home/user/AppImages/gearlever_obsidian.appimage" --backup-mechanism "git" --git-ops "pull" --git-ops "push" --install-gnome true

Would generated the following in: /home/user/.local/share/applications/oddsidian.desktop

[Desktop Entry]
Type=Application
Name=Oddsidian
Comment=An Obsidian sync utility and launcher
Exec=/home/user/Downloads/obsidian-sync-tool/obsidian_sync.sh --local-vault "/home/user/vaults/test" --obsidian-runtime "/home/user/AppImages/gearlever_obsidian.appimage" --backup-mechanism "git" --git-ops "pull" --git-ops "push"
Icon=/home/user/AppImages/.icons/gearlever_obsidian.png
StartupNotify=true
Terminal=false
Categories=Office

Tweak this file to meet your requirements.

The Obsidian Sync Tool is available on GitLab under a MIT license

Full instructions can be found at the GitLab repository.

Find what I do useful and would like to support me? Donations are not expected nor necessary but always appreciated.

• Buy me a coffee
• PayPal

Thanks for taking the time to read this and enjoy!