Installation

Installation Guide for Nimbly Compass

This guide will walk you through the process of setting up the Nimbly Compass documentation vault on your computer, including downloading Obsidian, cloning the repository, and configuring the Git integration for syncing.

Downloading and Installing Obsidian

1. Visit the official Obsidian website at https://obsidian.md/download
2. Download the version appropriate for your operating system (Windows, macOS, or Linux)
3. Install Obsidian by following the installation prompts
4. Launch Obsidian after installation is complete

Cloning the Compass Vault

Prerequisites

• Git installed on your computer. If not already installed:
  • Windows: Download and install from https://git-scm.com/download/win
  • macOS: Install via Homebrew with brew install git or download from https://git-scm.com/download/mac
  • Linux: Use your distribution’s package manager, e.g., sudo apt install git for Ubuntu/Debian

Method 1: Using Terminal/Command Line

1. Open Terminal (macOS/Linux) or Command Prompt/PowerShell (Windows)

2. Navigate to the directory where you want to store the vault:

   cd /path/to/desired/location

3. Clone the repository:

   git clone https://github.com/Nimbly-Technologies/compass.git

4. Open Obsidian and select “Open folder as vault”

5. Navigate to the cloned compass folder and select it

Method 2: Using Obsidian Git Plugin (After Initial Setup)

1. Complete the initial setup of Obsidian
2. Install the Obsidian Git plugin (see next section)
3. Use the “Clone an existing remote repo” command from the command palette (Ctrl+P or Cmd+P)
4. Enter the repository URL: https://github.com/Nimbly-Technologies/compass.git
5. Provide your GitHub credentials if prompted

Setting Up Obsidian Git Plugin

Installing the Plugin

1. Open Obsidian with the Compass vault
2. Go to Settings (gear icon in the left sidebar)
3. Select “Community plugins”
4. Turn off “Safe mode” if prompted
5. Click “Browse” to access the community plugins
6. Search for “Obsidian Git”
7. Click “Install”
8. After installation, enable the plugin by toggling it on

Configuring the Plugin

The Nimbly Compass vault comes with pre-configured settings for the Git plugin. The current configuration includes:

• Commit Message Format: “vault backup: {{date}}”
• Date Format: “YYYY-MM-DD HH:mm:ss”
• Auto Save Interval: 10 minutes
• Auto Pull on Boot: Enabled
• Pull Before Push: Enabled
• Show Status Bar: Enabled
• Tree Structure in Commit Body: Enabled
• Refresh Source Control: Enabled (every 7000ms)
• Show Branch in Status Bar: Enabled

Using Obsidian Git for Syncing

The Obsidian Git plugin adds several commands to Obsidian. Access them through the Command Palette (Ctrl+P or Cmd+P).

Key Features

• 🔁 Automatic commit-and-sync (commit, pull, and push) on a schedule
• 📥 Auto-pull on Obsidian startup
• 🔧 Source Control View for staging/unstaging and committing files
• 📜 History View for browsing commit logs and changed files
• 🔍 Diff View for viewing changes in a file
• 🔗 GitHub integration to open files and history in your browser

Essential Git Commands

Changes

• List changed files: Lists all changes in a modal
  • Command: Obsidian Git: List changed files
• Open diff view: Open diff view for the current file
  • Command: Obsidian Git: Open diff view
• Stage current file
  • Command: Obsidian Git: Stage current file
• Unstage current file
  • Command: Obsidian Git: Unstage current file

Commit

• Commit all changes: Only commits all changes without pushing
  • Command: Obsidian Git: Commit all changes
• Commit all changes with specific message: Custom commit message
  • Command: Obsidian Git: Commit all changes with specific message
• Commit staged: Commits only files that have been staged
  • Command: Obsidian Git: Commit staged
• Commit staged with specific message: Custom commit message for staged files
  • Command: Obsidian Git: Commit staged with specific message

Commit-and-sync

• Commit-and-sync: Commit all changes, pull, and push
  • Command: Obsidian Git: Commit-and-sync
• Commit-and-sync with specific message: Custom message for commit-and-sync
  • Command: Obsidian Git: Commit-and-sync with specific message

Remote

• Push: Upload your committed changes
  • Command: Obsidian Git: Push
• Pull: Download changes from the remote repository
  • Command: Obsidian Git: Pull
• Clone an existing remote repo: Clone a remote repository
  • Command: Obsidian Git: Clone an existing remote repo
• Edit remotes: Modify remote repository URLs
  • Command: Obsidian Git: Edit remotes

Repository Management

• Initialize a new repo: Create a new Git repository
  • Command: Obsidian Git: Initialize a new repo
• Create new branch: Create a new Git branch
  • Command: Obsidian Git: Create new branch
• Edit .gitignore: Edit the .gitignore file
  • Command: Obsidian Git: Edit .gitignore

UI Views

• Open source control view: Visual interface for Git operations
  • Command: Obsidian Git: Open source control view
• Open history view: See the commit history
  • Command: Obsidian Git: Open history view

Automatic Syncing

The plugin is configured to:

1. Automatically commit changes every 10 minutes
2. Automatically pull changes when Obsidian starts
3. Show changed files and current branch in the status bar

Platform-Specific Notes

Desktop Notes

Authentication

Some Git services may require further setup for HTTPS/SSH authentication. For GitHub:

• HTTPS: You may need to set up a personal access token
• SSH: Requires SSH key setup with your GitHub account

Linux-Specific Notes

• ⚠️ Snap version of Obsidian is not supported for Git integration
• ⚠️ Flatpak is not recommended, as it doesn’t have access to all system files
• ✅ Use AppImage or a package manager installation instead

Mobile Support (Experimental)

The plugin can work on mobile devices but has significant limitations:

Mobile Limitations

• No SSH authentication support
• Limited repository size due to memory restrictions
• No rebase merge strategy
• No submodules support

Performance Considerations

Depending on your device’s RAM, Obsidian may:

• Crash during clone/pull operations
• Create buffer overflow errors
• Run operations indefinitely

Tips for Mobile Use

The fastest way to work on mobile with large vaults is to:

• Stage individual files rather than all files at once
• Only commit staged files
• Keep repositories as small as possible

Best Practices for Collaboration

1. Pull Before Editing: Always pull the latest changes before starting to work
   • Command: Obsidian Git: Pull
2. Commit Regularly: Make small, focused commits with descriptive messages
   • Command: Obsidian Git: Commit all changes with specific message
3. Push After Significant Changes: Share your work with others
   • Command: Obsidian Git: Push
4. Check Status: Use the Source Control View to see the status of your changes
   • Command: Obsidian Git: Open source control view
5. Resolve Conflicts Early: Use the diff view to resolve merge conflicts

Troubleshooting

Common Issues and Solutions

1. Authentication Errors:

   • Ensure your Git credentials are correctly configured
   • Use a personal access token if password authentication is not working
   • For SSH, verify your SSH keys are set up correctly

2. Merge Conflicts:

   • Pull before making changes to minimize conflicts
   • Use the diff view to resolve conflicts manually

3. Plugin Not Working:

   • Check if the plugin is enabled in Settings → Community plugins
   • Ensure Git is properly installed and accessible from the command line
   • Restart Obsidian after making configuration changes

4. Mobile-Specific Issues:

   • Try working with smaller repositories
   • Stage and commit individual files instead of all at once
   • Consider alternative syncing methods for very large vaults

For more detailed information about the Obsidian Git plugin, visit the official repository.

---

If you encounter any issues or have questions about the setup process, please contact the documentation team for assistance.