# Desktop You can either start by cloning an existing remote repository as described [[#For existing remote repository|here]] or start with initializing a new repository locally and optionally push that to a remote repository as described [[#Create new local repository|here]]. ## Create new local repository 1. Follow the [[Installation]] instructions for your operating system 2. Call the `Initialize a new repo` command 3. Create your first commit by creating some files and calling the `Commit all changes with specific message` command 4. If you want to Setup to push it to a remote repository like to GitHub: 1. Setup [[Authentication]] 2. Ensure that the remote repository is empty. Otherwise delete the repository and instead proceed to clone the remote repository as described in the [[#For existing remote repository|next section]]. 3. Call the `Push` command. It should ask you for a name and URL of the remote repository. Just enter `origin` for the remote name and copy the URL to push to somewhere from your remote git service. ## For existing remote repository To clone, you have to use a remote URL. This can be one of two protocols: either `https` or `ssh`. This depends on your chosen [[Authentication]] method. `https`: `https://github.com/<username>/<repo>.git` `ssh`: `[email protected]:<username>/<repo>.git` 1. Follow the [[Installation]] instructions for your operating system 2. Setup [[Authentication]] 3. Git can only clone a remote repo in a new folder. Thus you have two options - Use the "Clone an exising remote repository" command to clone your repo into a subfolder of your vault. You then have again two choices - Move all your files from the new folder (including `.git` !) into your vault root. - Open your new subfolder as a new vault. You may have to install the plugin again. - Run `git clone <your-remote-url>` in the command line wherever you want your vault to be located. 4. Read on how to best configure your [[Tips-and-Tricks#Gitignore|.gitignore]] > [!info] iCloud and Git > When syncing your vault with iCloud and using Git on your desktop device the whole `.git` directory gets synced to your mobile device as well. This may slow down the Obsidian startup time. > - One solution is to put the git repository above your Obsidian vault. So that your vault is a sub directory of your git repository. > - Another solution is to move the `.git` directory to another location and create a `.git` file in your vault with only the following line: `gitdir: <path-to-your-actual-git-direcotry>` ## Vault inside a larger repository By default, the plugin manages the entire Git repository, including files outside the vault. Enable **Limit file operations to the vault** in the advanced settings to reduce file-oriented operations and file listings to the vault directory. This limits status, staging, unstaging, discarding, and submodule updates where possible. Git operations that apply to repository history or the working tree as a whole remain repository-wide. Pulling, merging, rebasing, checking out branches, fetching, pushing, and branch operations can therefore still affect files outside the vault. Repository history also remains global. Files outside the vault that were already staged are not unstaged by the plugin and are included in the next commit. The Source Control view shows their count without loading their paths. Conflicts outside the vault are also counted and must be resolved outside Obsidian before committing or pushing. The limit is path-based. If a file is moved from the vault to a directory outside it, Git treats that as a deletion inside the vault and an addition outside it. The deletion can be staged automatically, while the external addition is left unstaged. # Mobile The Git implementation on mobile is **very unstable**! I would not recommend using this plugin on mobile, but try other syncing services. One such alternative is [GitSync](https://github.com/ViscousPot/GitSync), which is available on both Android and iOS. It is not associated with this plugin, but it may be a better option for mobile users. A tutorial for setting it up can be found [here](https://viscouspotenti.al/posts/gitsync-all-devices-tutorial). Another alternative for iOS is [Working Copy](https://workingcopy.app/). ## Restrictions I am using [isomorphic-git](https://isomorphic-git.org/), which is a re-implementation of Git in JavaScript, because you cannot use native Git on Android or iOS. - SSH authentication is not supported ([isomorphic-git issue](https://github.com/isomorphic-git/isomorphic-git/issues/231)) - Repo size is limited, because of memory restrictions - Rebase merge strategy is not supported - Submodules are not supported - Symlinks are not supported because Obsidian's mobile file API does not provide operations to create or read them. - File permissions, including the executable bit, are not supported by Obsidian's mobile file API. File systems on different platforms allow different characters in filenames. A filename that works on macOS may fail on Android, preventing a pull or checkout. Use filenames that are valid on every device where you use the vault. ## Performance on mobile > [!danger] Warning > Depending on your device and available free RAM, Obsidian may > - crash on clone/pull > - create buffer overflow errors > - run indefinitely. > > It's caused by the underlying git implementation on mobile, which is not efficient. I don't know how to fix this. If that's the case for you, I have to admit this plugin won't work for you. So commenting on any issue or creating a new one won't help. I am sorry. ## Start with existing remote repository ### Clone via plugin Follow these instructions for setting up an Obsidian Vault on a mobile device that is already backed up in a remote git repository. The instructions assume you are using [GitHub](https://github.com), but can be extrapolated to other providers. 1. Make sure any outstanding changes on all devices are pushed and reconciled with the remote repo. 2. Install Obsidian for Android or iOS. 3. Create a new vault (or point Obsidian to an empty directory). Do NOT select `Store in iCloud` if you are on iOS. 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). - Minimal permissions required are - "Read access to metadata" - "Read and Write access to contents and commit status" 5. In Obsidian settings, enable community plugins. Browse plugins to install Git. 6. Enable Git (on the same screen) 7. Go to Options for the Git plugin (bottom of main settings page, under Community Plugins section) 8. Under "Identity", enter your Git server username. For the password or personal access token, create or select a secret. Existing saved passwords are moved to Obsidian's Secret Storage automatically when the plugin updates on that device. 9. Don't touch any settings under "Advanced" 10. Exit plugin settings, open command palette, choose "Git: Clone existing remote repo". 11. 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`. - `https://github.com/<username>/<repo>.git` - E.g. `https://github.com/denolehov/obsidian-git.git` 12. Follow instructions to determine the folder to place repo in and whether an `.obsidian` directory already exits. 13. Clone should start. Popup notifications (if not disabled) will display the progress. Do not exit until a popup appears requesting that you "Restart Obsidian". ### Clone via Working Copy on iOS Depending on the size of your repository and your device, Obsidian may crash during clone via the plugin. Alternatively, the initial clone can be done via [Working Copy](https://workingcopy.app/). None that this a paid app. The usual commit-and-sync can then be done via the plugin. The following guide assumes you don't commit your `.obsidian` directory. 1. Make sure any outstanding changes on all devices are pushed and reconciled with the remote repo. 2. Install Obsidian for Android or iOS. 3. Create a new vault (or point Obsidian to an empty directory). Do NOT select `Store in iCloud` if you are on iOS. 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). - Minimal permissions required are - "Read access to metadata" - "Read and Write access to contents and commit status" 5. Swipe up and away Obsidian to fully close it. Open Working Copy app. 6. Clone the repo using Working Copy. Instead of logging in to GitHub through the Working Copy interface, enter the clone URL directly. Then enter your username, and for the password your Personal Access Token. 7. Open Files app. 8. Copy the repo from Working Copy. Delete the vault from Obsidian and paste the repo there (repo has the same name as the vault). 9. Open Obsidian. 10. All your cloned files should be visible. 11. Install and enable the Git plugin. 12. Add your name/email to the "Authentication/Commit Author" section in the plugin settings. 13. Use the command palette to call the "Pull" command. ## Start with new repo 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. Also make sure to read on how to best configure your [[Tips-and-Tricks#Gitignore|.gitignore]].