Skip to content

Commit 443a922

Browse files
Vinzent03Vinzent03
committed
doc: add documentation
1 parent beafd20 commit 443a922

11 files changed

+245
-3
lines changed

‎README.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@
22

33
Plugin that allows you to back up your [Obsidian.md](https://obsidian.md) vault to a remote Git repository (e.g. private repo on GitHub).
44

5-
Requirements, installation steps (including setup for mobile), tips and tricks, common issues and more can be found in the [wiki](https://github.com/denolehov/obsidian-git/wiki/).
5+
Requirements, installation steps (including setup for mobile), tips and tricks, common issues and more can be found in the [documentation](https://publish.obsidian.md/git-doc).
66

77
For mobile users see [Mobile](#mobile) section below.
8+
89
## Highlighted Features
910

1011
- Automatic vault backup every X minutes
@@ -53,14 +54,14 @@ For mobile users see [Mobile](#mobile) section below.
5354

5455
## Authentication
5556

56-
Authentication may require additional setup. See more in the [Authentication documentation](https://github.com/denolehov/obsidian-git/wiki/Authentication)
57+
Authentication may require additional setup. See more in the [Authentication documentation](https://publish.obsidian.md/git-doc/Authentication)
5758

5859
### Obsidian on Linux
5960

6061
- ⚠ Snap is not supported.
6162
- ⚠ Flatpak is not recommended, because it doesn't have access to all system files.
6263

63-
Please use AppImage instead ([Linux installation guide](https://github.com/denolehov/obsidian-git/wiki/Installation#linux))
64+
Please use AppImage instead ([Linux installation guide](https://publish.obsidian.md/git-doc/Installation#Linux))
6465

6566
## Mobile
6667

‎doc/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.obsidian

‎doc/Authentication.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Linux
2+
3+
## Recommeded: HTTPS
4+
5+
### Storing
6+
7+
To securely store the username and password permanently without having to reenter it all the time you can use Git's [Credential Helper](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). `libsecret` stores the password in a secure place. On GNOME it's backed up by [GNOME Keyring](https://wiki.gnome.org/Projects/GnomeKeyring/) and on KDE [KDE Wallet](https://wiki.archlinux.org/title/KDE_Wallet).
8+
9+
```bash
10+
git config --global credential.helper libsecret
11+
```
12+
13+
You have to do one authentication action (clone/pull/push) after setting the helper in the terminal. Ater that you should be able to clone/pull/push in Obsidian without any issues.
14+
15+
In case you get the message `git: 'credential-libsecret' is not a git command`, libsecret is not installed on your system. You may have to install it by yourself.
16+
Here is an example for Ubuntu.
17+
18+
```bash
19+
sudo apt install libsecret-1-0 libsecret-1-dev make gcc
20+
21+
sudo make --directory=/usr/share/doc/git/contrib/credential/libsecret
22+
23+
# NOTE: This changes your global config, in case you don't want that you can omit the `--global` and execute it in your existing git repository.
24+
git config --global credential.helper \
25+
/usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret
26+
27+
```
28+
29+
### GUI Support
30+
31+
In case you don't want to store it permanently you can install `ksshaskpass` (it's preinstalled on KDE systems) and set it as binary to ask for the password.
32+
33+
NOTE: This changes your global config, in case you don't want that you can omit the `--global` and execute it in your existing git repository.
34+
35+
```bash
36+
git config --global core.askPass "ksshaskpass"
37+
```
38+
39+
You should get a prompt to enter your username/password in Obsidian now.
40+
41+
## SSH
42+
43+
By installing `ksshaskpass` (it's preinstalled on KDE systems) you can use SSH to authenticate. You have to add your SSH key to the `ssh-agent` and set `ksshaskpass` as binary to ask for the password.
44+
```bash
45+
sudo ln /usr/bin/ksshaskpass /usr/lib/ssh/ssh-askpass
46+
```
47+
48+
# macOS
49+
50+
## HTTPS
51+
52+
Run the following to use the macOS keychain to store your credentials.
53+
54+
```bash
55+
git config --global credential.helper osxkeychain
56+
```
57+
58+
You have to do one authentication action (clone/pull/push) after setting the helper in the terminal. After that you should be able to clone/pull/push in Obsidian without any issues.
59+
60+
# Windows
61+
62+
## HTTPS
63+
64+
Ensure you are using Git 2.29 or higher and you are using Git Credential Manager.
65+
You can verify this by executing the following. It should ouput `manager`.
66+
67+
```bash
68+
git config credential.helper
69+
```
70+
71+
Just execute any authentication command like push/pull/clone and a pop window should come up, allowing your to sign in.

‎doc/Common issues.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## xcrun: error: invalid developer path
2+
3+
This is an error occurring only on macOS. It's easy to fix though. Just run the following snippet in the terminal. `xcode-select --install` See #64 as an example.
4+
5+
## Error: spansSync git ENOENT
6+
7+
This occurs, when the plugin can't find the git executable. It takes it from the PATH. Head over to [[installation]] to see if everything is properly installed for your platform.
8+
9+
## Infinite pulling/pushing with no error
10+
11+
That's most time caused by authentication problems. Head over to [[Authentication]]

‎doc/Features.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Submodules Support
2+
3+
Since version 1.10.0 submodules are supported. While adding/cloning new submodules is still not supported (Might come later), updating existing submodules on the known "Create Backup" and "Pull" commands is supported. This works even recursively. "Create Backup" will cause to add, commit and push (if turned on) all changes in all submodules. This feature needs to be turned on in the settings.
4+
5+
Additional **requirements**:
6+
7+
- Checked out branch (not just a commit as it is when running `git submodule update --init`)
8+
- Tracking branch is set up, so that `git push` works
9+
- Tracking branch needs to be fetched, so that a `git diff` with the branch works

‎doc/Getting Started.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Desktop
2+
3+
## For existing remote repository
4+
5+
For cloning you have to use an remote url. This can be one of two protocols. Either `https` or `ssh`. This depends on your choosen [[Authentication]] method.
6+
`https`: `https://github.com/<username>/<repo>.git`
7+
`ssh`: `git@github.com:<username>/<repo>.git`
8+
9+
1. Follow the [[Installation]] instructions for your operating system
10+
2. Setup [[Authentication]]
11+
3. Git can only clone a remote repo in a new folder. Thus you have two options
12+
- Use the "Clone an exising remote repository" command to clone your repo into a subfolder of your vault. You then have again two choices
13+
- Move all your files from the new folder (including `.git` !) into your vault root.
14+
- Open your new subfolder as a new vault. You may have to install the plugin again.
15+
- Run `git clone <your-remote-url>` in the command line wherever you want your vault to be located.
16+
17+
# Mobile
18+
19+
## For existing remote repository
20+
21+
Follow these instructions for setting up an Obsidian Vault on a mobile device that is already backed up in a remote git repository.
22+
23+
The instructions assume you are using [GitHub](https://github.com), but can be extrapolated to other providers.
24+
25+
1. Make sure any outstanding changes on all devices are pushed and reconciled with the remote repo.
26+
2. Install Obsidian for Android or iOS.
27+
3. Create a new vault (or point Obsidian to an empty directory). Do NOT select `Store in iCloud` if you are on iOS.
28+
4. If your repo is hosted on GitHub, [authentication must be done with a personal access token](https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/). Detailed instruction for that process can be found [here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
29+
- Minimal permissions required are
30+
- "Read access to metadata"
31+
- "Read and Write access to contents and commit status"
32+
1. In Obsidian settings, enable community plugins. Browse plugins to install Obsidian Git.
33+
2. Enable Obsidian Git (on the same screen)
34+
3. Go to Options for the Obsidian Git plugin (bottom of main settings page, under Community Plugins section)
35+
4. Under the "Authentication/Commit Author" section, fill in the username on your git server and your password/personal access token.
36+
5. Don't touch any settings under "Advanced"
37+
6. Exit plugin settings, open command palette, choose "Obsidian Git: Clone existing remote repo".
38+
7. Fill in repo URL in the text field and press the repo URL button below it. The repo URL is NOT the URL in the browser. You have to append `.git`.
39+
- `https://github.com/<username>/<repo>.git
40+
- E.g. `https://github.com/denolehov/obsidian-git.git`
41+
9. Follow instructions to determine the folder to place repo in and whether an `.obsidian` directory already exits.
42+
10. Clone should start. Popup notifications (if not disabled) will display the progress. Do not exit until a popup appears requesting that you "Restart Obsidian".
43+
44+
## New Repo
45+
46+
Similar steps as [existing repo](#existing-repo), except use the `Initialize a new repo` command, followed by `Edit remotes` to add the remote repo to track. This remote repo will need to exist and be empty.
47+
48+
49+

‎doc/Installation.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
2+
> [!important]
3+
> Although the plugin itself is desktop platform independent, an incorrect installation of Obsidian or Git may break the plugin.
4+
5+
## Plugin installation
6+
7+
### From within Obsidian
8+
Go to "Settings" -> "Community plugins" -> "Browse", search for "Obsidian Git", install and enable it.
9+
10+
### Manual
11+
1. Download `obsidian-git-<latest-version>.zip` from the [latest release](https://github.com/denolehov/obsidian-git/releases/latest)
12+
2. Unpack the zip in `<vault>/.obsidian/plugins/obsidian-git`
13+
3. Reload Obsidian (CTRL + R)
14+
4. Go to settings and disable restricted mode
15+
5. Enable `Obsidian Git`
16+
17+
# Windows
18+
19+
## Git installation
20+
21+
> [!info]
22+
> Ensure you are using Git 2.29 or higher.
23+
24+
Install Git from the official [website](https://git-scm.com/download/win) with all default settings.
25+
Make sure you have `3rd-party software` access enabled.
26+
27+
![[third-party-windows-git.png]]
28+
29+
Enable Git Credential Manager. You can verify this for existing installations by executing the following. It should ouput `manager`.
30+
31+
```bash
32+
git config credential.helper
33+
```
34+
35+
![[credential-manager-windows-git.png]]
36+
37+
38+
# Linux
39+
40+
## Obsidian installation
41+
42+
Known **supported** Obsidian installation methods:
43+
- AppImage
44+
45+
Known **not fully supported** package managers
46+
- Snap (Snap puts Obsidian in a kind of sandbox, so that Obsidian can't access Git)
47+
- [Flatpak](https://flathub.org/apps/details/md.obsidian.Obsidian) can access Git, but not all system files, so it's not recommended.
48+
49+
If you installed Obsidian a while ago via **Flatpak**, and it doesn't work, please run the following snippet.
50+
51+
```
52+
$ flatpak update md.obsidian.Obsidian
53+
$ flatpak override --reset md.obsidian.Obsidian
54+
$ flatpak run md.obsidian.Obsidian
55+
```
56+
[Source of this snippet](https://github.com/flathub/md.obsidian.Obsidian/issues/5#issuecomment-736974662)
57+
58+
## MacOS
59+
60+
Nothing specific.

‎doc/Start here.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Obsidian-Git Documentation
2+
3+
## Topics
4+
- [[Installation]]
5+
- [[Getting Started]]
6+
- [[Common issues]]
7+
- [[Tips-and-Tricks]]
8+
- [[Features]]
9+
10+
> [!warning] Obsidian installation on Linux
11+
> Please don't use Flatpak or Snap to install Obsidian on Linux. Learn more [[Installation#Linux|here]]
12+
13+
14+
## What is Git?
15+
16+
Git is a version control system. It allows you to keep track of changes to your notes and revert back to previous versions. It also allows you to collaborate with other people on the same files. You can read more about Git [here](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control).
17+
18+
> [!info] Git/GitHub is not a syncing service!
19+
> Git is not meant to share your changes live to the cloud or another person. Meaning it should not be used to work with someone live on the same note. However it's perfect for async collaboration.
20+
21+
You build your history by batching multiple changes into commits. These can then be reverted or checked out. You can view the difference between version of a note via the [Version History Diff](obsidian://show-plugin?id=obsidian-version-history-diff) plugin.
22+
Git itself only manages a local repository. It becomes really handy in conjunction with an online remote repository. You can push and pull your commits to/from a remote repository to share or backup your vault. The most popular provider is [GitHub](https://github.com).
23+
24+
Git is primarily used by developers and thus the command line is sometimes needed. Obsidian-Git is a plugin for Obsidian that allows you to use Git from within Obsidian without always having to use the command line or leaving Obsidian.

‎doc/Tips-and-Tricks.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Tips and Tricks
2+
3+
## Gitignore
4+
5+
To exclude cache files from the repository, create `.gitignore` file in the root of your vault and add the following lines:
6+
```
7+
# to exclude Obsidian's settings (including plugin and hotkey configurations)
8+
.obsidian/
9+
10+
# OR only to exclude workspace cache
11+
.obsidian/workspace.json
12+
13+
# Add below lines to exclude OS settings and caches
14+
.trash/
15+
.DS_Store
16+
```

‎doc/assets/credential-manager-windows-git.png

14.3 KB
Loading

0 commit comments

Comments
 (0)