# Obsidian - Sync Vaults Between PCs with Github ![[images/Obsidian-Sync-Vaults-Between-PCs-with-Github.webp]] [Watch on YouTube](https://www.youtube.com/watch?v=gOdh8wdbxm4) · 22:55 · Josh Plunkett · 2023-02-12 > Written from the video's English captions (fetched with youtube-transcript-api after yt-dlp's subtitle request hit a 429 error), with the creator's chapter list as section anchors. Prices are the ones Josh quoted in February 2023. ## Outline ### 00:00 Introduction to syncing - Today's topic is keeping your vault in sync with another PC or device. - If you're coming from **OneNote** or a web-based, always-online tool like **Notion**, Obsidian can be "a little bit of a shell shock," because it's a local application with no built-in online copy. - The upside: Obsidian is a local install that stores everything as **ordinary folders and files**, so you can use almost any backup or sync method you already know. ### 00:50 Official Obsidian sync - The official option is **Obsidian Sync** (`obsidian.md/sync`), a paid subscription at **$10 per month or $96 per year** when he recorded. - He'd almost call it the recommended way if you're on **Apple devices** (a Mac plus an iPhone or iPad), because Apple's locked-down "walls" mean the methods he recommends later won't work as well there. - It also pays Obsidian and helps fund development. He notes the team had grown by at least two people in the past year, including a new COO. - He hasn't tried it himself. He syncs his vaults other ways and doesn't think Sync is right for him. ### 02:38 Alternative sync methods - He drew the options in **Excalidraw** inside his vault: one computer on the left, another on the right, and every method in between. Data flows both ways in each case. ![[images/Obsidian-Sync-Vaults-Between-PCs-with-Github-t0170.webp]] *His "Excalidraw - Sync Methods" note (Tutorials / YouTube Series / Sync Methods in the ObsidianTTRPGVault, Obsidian v1.1.12): a PC linked through a USB stick, Google Drive ("Free plan 15Gb, $12.50 per month for 2Tb"), OneDrive ("Free plan 5Gb, $3 per month 100GB"), GitHub ("Free for Public Facing Sites, $3.70 per month for Private 100GB"), Obsidian Sync ("$10 per month, 10GB per vault"), and Sync Thing ("Free") to a second PC, an iPhone, and an Android phone.* - **What a vault actually is**: a folder containing a hidden `.obsidian` folder that stores all your settings, "and I mean all of your settings," down to your active tab, which plugins and themes are installed, and so on. Everything else is your content, mirroring the folder tree you see in Obsidian. OneNote, by contrast, keeps your data in a back-end database you can't easily reach. ![[images/Obsidian-Sync-Vaults-Between-PCs-with-Github-t0205.webp]] *File Explorer open on his ObsidianTTRPGVault folder on the TTRPG (F:) drive: `.git`, `.obsidian`, Shared Content, Tutorials, z_Assets, z_Templates, `data.json`, `Inline Script.md`, and `README.md`.* - **USB stick**: store the vault on a USB drive, unplug it, carry it to the next computer, and open it there. The drive letter has to map the same way each time or it gets confusing, and it can be slow, so he doesn't recommend it. - **Google Drive and OneDrive**: keep the vault folder in your synced drive and open it from there. Plenty of people use these and they work well, though he's heard of trouble on Apple devices. A bonus is that you can browse the files from anywhere. - **Obsidian Sync**: the paid service from earlier. He suspects it probably uses GitHub behind the scenes, since "a lot of the stuff feels the same," but says he doesn't know. - **Syncthing**: free, and he has a separate video on it. It works well from a Windows PC to an **Android** phone, but not for iPhones, and he doubts it would work on a Mac. ### 06:13 GitHub sync benefits - **GitHub** is his own preferred method. His Patreon tutorial vault lives on GitHub, and its **permission-based controls** let him give patrons access. - GitHub is a **code repository** built so many people can edit the same code at once. Technically you can collaborate live on a vault: they've had 5 to 10 people connected to one vault submitting changes. That's more advanced and saved for a later video. - His day-to-day use is simpler: he works on his main computer, syncs to GitHub, and pulls the vault onto the computer at the back that he runs his games from. - **Reading notes on the web**: github.com renders Markdown, so you can open a note such as last night's "Working with PDFs" and read it in the browser. Plugin features won't render because GitHub doesn't understand them, but you could technically edit in real time there. - **Edit history**: open a file (his example is custom CSS), click **History**, and you see every commit (46 in his example). Inside a commit, **red** lines were removed and **green** lines were added, so if he breaks something he can find an old version of a note. - **Cost**: public repositories are free, with what he believes is about 100 GB of space. He pays for private repositories, which he priced at **$3.70 per month** (probably AUD, billed annually), because he keeps six or seven vaults, many containing copyrighted text copied from official books that he can't share publicly. > [!note] GitHub plans and limits > GitHub's free plan has included unlimited private repositories since January 2019, so you don't need to pay just to keep a vault private. GitHub also asks that repositories stay small (ideally under 1 GB) and blocks single files over 100 MB, which matters if your vault holds lots of maps, PDFs, or images. Check GitHub's current plans and limits before relying on the figures from 2023. ### 10:45 Setting up GitHub desktop - Download **GitHub Desktop** from `desktop.github.com`. It has a Windows download; on another operating system, search for the recommended Git client. He also has the command-line **Git** installed, but GitHub Desktop is "nice and simple and easy to use." - On first launch it will prompt you to create or open a repository. - For the demo he creates a fresh vault, **TestVault20231202**, in the Obsidian folder where all his vaults live, and adds a note ("This is my new note"). Any vault, old or new, works the same way. - In GitHub Desktop: **File > Add local repository**, then **Choose…** and select the vault folder. ![[images/Obsidian-Sync-Vaults-Between-PCs-with-Github-t0790.webp]] *GitHub Desktop's Add local repository dialog with the local path `F:\Obsidian\TestVault20231202` and the warning "This directory does not appear to be a Git repository. Would you like to create a repository here instead?"* - Click the **create a repository** link, keep the name, tick the option to add a README, and click **Create repository**. - Back in File Explorer the vault now has a `.git` folder and a `.gitattributes` file alongside `.obsidian`, the README, and the new note. - He adds a new folder with a "Second New Note" in Obsidian, and GitHub Desktop immediately lists the changes. That's what it's good at: it watches the folder and keeps a list of everything that changed. ### 14:40 Pushing and pulling files - Click **Publish repository**. You'll need a github.com account and must be signed in through the app. He keeps the name and ticks **Keep this code private** (he pays for that; the free public option works too), then publishes. - **Fetch** pulls the latest changes from GitHub down to your computer. - **Commit**: give the change a summary and an optional description so you can keep track of what you did, then click **Commit to main**. That puts the change in a bucket ready to send. ![[images/Obsidian-Sync-Vaults-Between-PCs-with-Github-t0940.webp]] *Committing in GitHub Desktop with the summary "12022023 YT Video" while the diff of `.obsidian/workspace.json` shows Obsidian's own tab state changing (for example "New Note.md" replaced by "New Folder/Second New Note.md" and a new `currentTab` value).* - Then click **Push origin** to send it up to GitHub. - On github.com, under his repositories, the new repository is "almost word for word" a copy of the vault folder: the README, `.gitattributes`, the new note, and the new folder with its second note. The `.git` folder is hidden but there. - **On another computer**: install GitHub Desktop, choose **File > Clone repository**, pick the repository from your list, choose where it goes, and click **Clone**. His demo clone landed inside the vault itself, "probably not the best place," but it shows it works. ### 17:35 Workflow and best practices - **His biggest tip**: work on one computer, push to GitHub, then **close Obsidian** on that computer. While Obsidian is open it keeps writing to files, and Git hates conflicting changes to the same file, which leads to confusing merge messages asking which version to keep. - The routine: on the next computer, open GitHub Desktop, press **Fetch** to download the changes, open Obsidian, run your session, then push with a summary and description and close Obsidian again. Repeat in the other direction. - If you open Obsidian on both machines at once, you'll most likely get conflicts in the files that track open tabs, and fixing them usually means throwing away one side's changes, which is risky because you never quite know which you're keeping. - A second demo: he creates "Third File," commits it with the summary "Push 12022023" and description "This is my push" ("my spelling is terrible"), and pushes. ![[images/Obsidian-Sync-Vaults-Between-PCs-with-Github-t1225.webp]] *The commit on github.com for ObsidianTTRPGProject/TestVault20231202 (shown as a Public repository): "Push 12022023 / This is my push," with 2 changed files and 20 additions and 5 deletions. The changes are a new `Third File.md` and edits to `.obsidian/workspace.json`, with removed lines in red and added lines in green.* - On github.com you can open a push to see exactly what changed, list all commits under **Commits**, view commit details, and **browse the repository** as it was at any commit, a snapshot you can use to recover an earlier version of a broken note. - **Automatic option**: install command-line Git and the **Obsidian Git** community plugin, which can push and pull on a timer. He prefers manual control because he had fewer errors and write conflicts that way, so he pushes and pulls at each session. - Wrap-up: GitHub sync is free for public repositories, and the private option is still cheaper than Obsidian Sync by his maths. Lots of people in the Obsidian world use GitHub regularly, so it pays to get familiar with it. Thanks to his patrons, who've turned this into "a passionate side job." ## Things mentioned ### Sync and backup methods - **Obsidian Sync**, the official paid service: $10 per month or $96 per year in February 2023, 10 GB per vault in his diagram - **USB stick**: carry the vault between computers (slow; keep the drive letter consistent) - **Google Drive**: free plan 15 GB, $12.50 per month for 2 TB in his diagram - **OneDrive**: free plan 5 GB, $3 per month for 100 GB in his diagram - **Syncthing**: free peer-to-peer sync, good for Windows to Android - **GitHub**: free public repositories; he paid $3.70 per month for private ones ### Git and GitHub tools - **GitHub Desktop** (`desktop.github.com`): Add local repository, Create repository, Publish repository, Keep this code private, Fetch, Commit to main, Push origin, Clone repository - **Git** (command line), which he has installed as an alternative - **github.com** features: Markdown rendering of notes, file History, commit lists, red/green diffs, Browse files at a commit, and collaborator permissions - Files Git adds to a vault: `.git` and `.gitattributes`, plus an optional README ### Obsidian features and plugins - The hidden **`.obsidian`** settings folder, including `workspace.json`, which tracks open tabs and causes most sync conflicts - **Excalidraw** plugin, used to draw his sync-methods diagram - **Obsidian Git** community plugin for automatic, timed pushes and pulls ### Other apps compared - **OneNote** and **Notion**, cloud-first note apps people often move to Obsidian from ### Links - [Obsidian](https://obsidian.md/) - [GitHub](https://github.com/) - [Obsidian Sync](https://obsidian.md/sync) - [GitHub Desktop](https://desktop.github.com/) - [Official Obsidian Discord](https://discord.gg/obsidianmd) - [Obsidian TTRPG Users Facebook group](https://www.facebook.com/groups/obsidianttrpgusers) - [Josh's Patreon](https://www.patreon.com/JPlunkett) - Related: [[Obsidian Sync - Sync notes between PC and Mobile]], [[Obsidian - Lets Talk About Backups]], [[Obsidian - Optimize your Vault and Publish Site]] ### Free vs paid (quick) - Free: Obsidian, GitHub Desktop, Git, public GitHub repositories, Syncthing, the Obsidian Git plugin, and the free tiers of Google Drive and OneDrive - Paid: Obsidian Sync, larger Google Drive or OneDrive storage, the GitHub plan he used for private repositories, and Josh's Patreon (tutorial vault on GitHub, private Discord, and support) ## Bios - **Josh Plunkett**: Australian GM and educator behind Obsidian TTRPG Tutorials (YouTube, Patreon, Discord). He keeps six or seven vaults in private GitHub repositories, runs his games from a second computer, and shares his tutorial vault with patrons through GitHub permissions. - **Obsidian team**: The small company behind Obsidian and Obsidian Sync. Josh notes it had grown by at least two people in the year before this video, including a new COO, and that Sync subscriptions help fund development. - **GitHub**: The Microsoft-owned code hosting service built on Git, which lets many people work on the same files and keeps a full change history. Josh uses it as a free or low-cost alternative to Obsidian Sync.