Obsidian Git

If you mange a lot of documentation (like me) and wish that it was easier to find related documents, manage them using Git, and have them all support LaTeX, then Obsidian may be for you.

I’m starting to use Obsidian to manage my documentation vault. I have to manage a lot of markdown documents that are edited by several people using Git, and I really don’t like editing markdown in its native form, then waiting for it to render. Obsidian allows for real-time rendering of markdown documents, include Rmarkdown formats (although this does require a plugin).

Another reason why I’m liking Obsidian is that it handles linking (they call it backlinking) so that a folder of documents can act very much like a wiki. The more documents you link, and the more you fill out the metadata (using tags and groups, etc…) the more you can use the Graph feature of Obsidian. This allows you to traverse your vault of documents much easier, and makes it just a bit faster to find your references and citation sources.

Now, I probably wouldn’t use Obsidian if it weren’t for the Git aspect. I need to be able to store and share my documentation vault with collaborators and colleagues, including being able to handle different versions of the documentation on different branches depending on the status of the document. However, out-of-the-box Obsidian does not have Git and you must download and enable a community-developed plugin to get this working.

Unfortunately, I made a few basic errors when I tried to set this up for the first time on my machine. I had just installed a fresh copy of Windows 11 (64-bit) and did not have any Git or Keys set up, and inevitably did a few things in the wrong order. So I decided to dedicate this blog post to describe how I managed to get Obsidian working with Git and GitHub on my Windows 11 machine.

Ensure Git is Working

Before we even think about installing Obsidian you are going to want to make sure Git is working correctly on your system. This is because we will be opening, editing and saving files to a remote repository using Obsidian.

Download & Install Git

If you haven’t already, download and install Git for Windows 11 from here: https://git-scm.com/downloads.

Follow the first-time use instructions here [3] to setup Git on your local machine.

Create a Local Repository

Use Windows Explorer to go to a folder where you want to clone this repository to use with Git and Obsidian (e.g. c:\users\<your username>\Git_Projects) and create a brand new folder there (e.g. Vault) to contain your cloned repository. We will only be using this for the automatically generated .git folder.

Now right-click anywhere in this empty folder and GitBash here . A new MinGW64 window will pop up.

You’ll want to initialise Git in this folder, so type in

$ git init

The path should now display the master branch label.

Create a new Remote Repository

Now we need to create a remote repository to clone.

Log in to your GitHub account here: https://github.com, go to your repositories and click the New button. I’ve called my repo Vault because that is the same name that Obsidian uses. Make it private, and set licence to None. Click Create Repository.

Clone the Repository

Now you can clone the remote repository to local using command line or GitHub.

If you want to use your Git Bash session from before, simply execute the following:

(master) $ git clone https://github.com/<Your GitHub Name>/<Your Doco Vault Name>.git

where this command can be taken straight from your GitHub settings:

Once you have cloned the remote master to your local GitHub folder it is best practice to work immediately from a branch. We will use the default naming convention and move immediately to the main branch using the following command line:

(master) $ git checkout -b main

Your Git Bash should now look like this:

You should now be ready to link/connect your local repo with the remote repo using an SSH key and a config. We cover this step in the next section.

Generating SSH and RSA Keys

Next, go to your GitHub account menu in the top right corner and click on Settings. Then, on the left-hand side menu click on SSH and GPG keys. Check if you have any Authentication Keys. If you do, then skip the next sub-section.

You will need to have an SSH key setup and registered on both ends: Your GitHub account will need an SSH key and your local Git will need one. To check if your local Git has an SSH key already set up, go to your Git Bash session and type in:

(master) $ ls -al ~/.ssh

This will show any existing SSH Keys. This will probably be empty, so let us continue.

Since you have not set up yor SSH Key go back to your Git Bash session and type in:

(master) $ ssh-keygen -t ed25519 -C "<your email address linked to your GitHub account>"

This command creates a new SSH key, using your GitHub email as a label. When you’re prompted to “Enter a file in which to save the key“, just press Enter to accept the default file location (which will be the hidden folder here:: C:\Users\<Your Name>\.ssh. ). Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key. To do so, type the default file location and replace id_ssh_keyname with your custom key name.

Now browse to your hidden folder located here: C:\Users\<Your Name>\.ssh. You should now have a file called id_ed25519. Inside it will be a long key surrounded by -----BEGIN OPENSSH PRIVATE KEY----- and -----END OPENSSH PRIVATE KEY-----.

To generate an RSA key, go back to your Git Bash session and type in:

(master) $ ssh-keygen -o

This command confirms where you want to save the key (.ssh/id_rsa), and then it asks twice for a passphrase, which you can leave empty if you don’t want to type a password when you use the key. However, if you do use a password, make sure to add the -o option; it saves the private key in a format that is more resistant to brute-force password cracking than is the default format.

Connecting your Local Machine to Remote GitHub

Now that we have our Keys we can connect our local machine to the remote master.

Login and go to your GitHub account menu in the top right corner and click on Settings. Then, on the left-hand side menu click on SSH and GPG keys. Click on the New SSH Key button and follow the prompts. When you’re done, your GitHub account should have a brand new authenticated SSH Key added to it.

Checking your SSH Connection

Go and open Git Bash session again and type in the following

(master) $ ssh - T git@github.com

It should response with a successful authetication and return your actual GitHub name.

Download & Install Obsidian

Now that we are sure that our local machine is communicating successfully with remote GitHub we can go ahead and download Obsidian for Windows 11 (64-bit) from here: https://obsidian.md/download.

Upon opening for the first time you should see

Click on Open Folder as Vault.

Obsidian will open a new, empty workspace panel.

Before we do anything, we need the Git plugin. Click on cog settings icon in the bottom left-hand corner. Then under Options click on Community plugins. Follow the prompts to unrestrict Obsidian, then click on the Browse community plugins button.

Search for Obsidian Git in the search bar, click on it, install and enable. Close the Settings.

Back on the main workspace click New Note and call it Readme. Type in something like This is a test.

Obsidian Git Source Control

The Obsidian Git plugin also has a nice Source Control view. Hold Ctrl+P to open Obsidian’s command prompt and type in

Obsidian Git: Open source control view

You should see:

The buttons

allow you to:

1. Backup
2. Commit
3. Stage All
4. Unstage All
5. Push
6. Pull
7. Change Layout, and
8. Refresh

It also gives you a nice Diff Viewer:

Create a New File to Commit and Push

Back on the main workspace click New Note and call it Readme. Type in something like Another change.

Note that we have created a new markdown file inside Obdisian’s vault, not the cloned repo! Since we have now added a new file to Obsidian’s vault (which contains a .git that is linked to remote via SSH Keys), let us see if we can use the Obsdiain Git plugin to commit this new file. Hold Ctrl+P to open up Obdisian’s command prompt and type in:

Obsidian Git: Commit all changes

It should say: Committed 1 File.

Now type in

Obsidian Git: Push

It should push 1 file to your remote branch.

Checking an Obsidian Push using GitHub Desktop

We can check that Obsidian has pushed the file correctly using GitHub Desktop. Go an open GitHub Desktop and click the Vault Repository History:

Using Source View Instead of Commands

Instead of holding Ctrl+P to open Obsidian’s command line everytime you want to perform an Git action, you can use the Git plugin’s command view. To access, simply type

Conclusion

In the next blog on Obsidian we will discess setting it up, configuring it and seeing what we can do with it.

Appendix – Troubleshooting

Obsidian Git Push Permission Denied

First you must make sure you have your SSH and RSA keys generated and stored in your C:\Users\<Your Name>\.ssh folder. These will have been generated (above) on the command line in your local Git Bash session.

Now you’ll need to make a config file using Git Bash.

Go back to you Git Bash session (the one that is currently configured to your .ssh folder) and type in:

$ touch ~/.ssh/config

This will create a config file in the hidden ssh directory.

Open the config file in an editor (e.g. VS Code) and add the following lines of code:

Host *
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_rsa

Now change the location of the RSA file by executing the following line of code:

$ ssh-add -k ~/.ssh/id_rsa

If successful, it will prompt you for your RSA passphrase. Enter it, and it should say that the Identity has been added.

My Exact Settings

I have 3 files in my C:\Users\<My Name>\.ssh folder:

1. config
2. id_rsa
3. id_ed25519

…and all three were generated by Git Bash, in the folder.

My config file reads:

Host *
    AddKeysToAgent yes
    #UseKeychain yes  # Note that this was commented out.
    IdentityFile ~/.ssh/id_ed25519
    #IdentityFile ~/.ssh/id_rsa  # I'm using SSH
    IgnoreUnknown UseKeychain

Move Git Folder to Obsidian Vault Folder

Note that I have a separate folder for my locally cloned GitHub repository here: C:\Users\<My Name>\Git_Projects\Vault, which I cloned with GitHub Desktop. I did this separately so that I could grab the hidden .git folder that it automatically generates.

Then, separately, I have another folder which I created using Obsidian: C:\Users\<My Name>\Vault. This folder comes automatically with a hidden .obsidian folder (which I leave alone), but now I cut and paste that .git folder to this folder. Now I have two hidden dot-folders in the Obsidian Vault folder.

Now, before opening Obsidian, I open GitHub desktop and see that it cannot locate the Git folder (because I moved it). So I relocate the Git folder using the GitHub Locate Repository feature. It repoints to the Git folder that is now located in my Obsidian Vault folder. A bunch of changes are automatically made with this move, so I quickly use GitHub to commit and push to remote.

Next, I re-open my Obsidian application. I am now able to push to my remote branch using the Obsidian Git Push command.

I basically had to follow the readme file from [4] to get it working.

Dealing with Non-Fast-Forward Errors

See [6] for resolution.

References

[1] Git, https://git-scm.com/downloads.

[2] GitHub, https://github.com.

[3] GitHub, Getting Started – First-Time Git Setup, https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup.

[4] GitHub, Obsidian Git Tutorial for Windows, https://github.com/gitobsidiantutorial/obsidian-git-tut-windows/blob/main/README.md.

[5] Danny Hatcher, Obsidian Git for Beginners, https://dannyhatcher.com/obsidian-git-for-beginners (2023)

[6] GitHub, Dealing with Non-Fast-Forward Errors, https://docs.github.com/en/get-started/using-git/dealing-with-non-fast-forward-errors.

[7] Reddit, Figuring out the SSH config file settings for Obsidian on Windows 11, https://www.reddit.com/r/ObsidianMD/comments/10bx50b/obsidian_git_ssh_are_they_incompatible/ (2023)

[8] Obsidian website.

[9] Obsidian Help.