How to Use QMD to Manage Collections on Network Drives: A Complete Guide

Yes, QMD can manage collections on network drives because it treats all filesystem paths uniformly, storing absolute paths in ~/.config/qmd/index.yml and resolving them via realpathSync without enforcing local-disk restrictions.

QMD is a lightweight document management system that organizes files into searchable collections. If you are wondering whether QMD can manage collections located on network drives, the answer is definitively yes—the codebase treats NFS mounts, SMB shares, and local directories identically.

How QMD Handles Filesystem Paths

Path Storage and Resolution

In src/collections.ts, the addCollection function stores the absolute path you provide verbatim in the configuration file at ~/.config/qmd/index.yml. When QMD later needs to resolve a collection, src/store.ts invokes getRealPath, which calls realpathSync to normalize the path. This process works identically for /mnt/nfs/projects, Z:\docs, or //server/share.

Collection Detection Logic

The detectCollectionFromPath function in src/qmd.ts (lines 992-1005) performs simple string prefix matching against the stored absolute paths. Because the implementation relies on standard Node.js filesystem primitives rather than platform-specific checks, it imposes no distinction between local disks and network-mounted storage.

Requirements for Network Drive Collections

To successfully manage collections on network drives, ensure your environment meets these criteria:

• Mounted and Accessible: The network share must be mounted and reachable by the user running qmd. Unmounted paths will cause realpathSync to throw an error.
• Absolute Paths: Always specify absolute paths (e.g., /mnt/share or \\server\share). Relative paths may resolve incorrectly when the working directory changes.
• Stable Mount Points: While QMD stores the resolved path, network interruptions do not corrupt the index; however, operations will fail if the drive is disconnected during execution.

Practical Examples

Adding a Network Collection via CLI

# Add an NFS-mounted directory

qmd collection add /mnt/nfs/projects --name nfs-projects

# Add a Windows SMB share (mounted as Z:)

qmd collection add Z:/docs --name smb-docs

# Verify the collection is recognized

qmd collection list

Managing Collections Programmatically

// In a Node.js script using the QMD API
import { addCollection, listCollections } from "./src/collections";

// Register a network-mounted collection
addCollection("remote-research", "/mnt/nfs/research-data");

// Display all configured collections
console.log(listCollections());

Performance Considerations

When using QMD with network drives, indexing and search performance depend entirely on network latency and bandwidth. The getRealPath resolution and file scanning operations in src/store.ts execute synchronously; high-latency connections may cause noticeable delays during initial collection setup or full-index rebuilds. For optimal performance, ensure your network mount uses a low-latency protocol (NFSv4, SMB 3.0+) and that the QMD configuration directory (~/.config/qmd/) remains on local storage.

Summary

• QMD treats network drives identically to local directories because it uses standard Node.js filesystem APIs without platform restrictions.
• The addCollection function in src/collections.ts stores absolute paths verbatim, while getRealPath in src/store.ts resolves them using realpathSync.
• Any mounted network location—NFS, SMB, or UNC paths—works as a collection source provided it uses absolute paths and remains accessible.
• Performance correlates with network speed; local storage for the QMD index remains recommended.

Frequently Asked Questions

Does QMD support Windows UNC paths like \\server\share?

Yes. QMD delegates path resolution to the Node.js realpathSync implementation, which handles Windows UNC paths correctly. When adding a collection on Windows, you can use \\server\share\folder or map the share to a drive letter like Z:\folder; both formats resolve to absolute paths stored in ~/.config/qmd/index.yml.

Will QMD lose track of collections if the network drive disconnects?

No, the collection entry persists in the configuration file even if the network mount becomes unavailable. However, operations that require filesystem access—such as indexing or querying documents—will fail with a "path not found" error until the drive is remounted. Once connectivity is restored, QMD resumes normal operation without requiring reconfiguration.

Is there a performance penalty when using network drives with QMD?

Yes, performance depends on network latency and bandwidth. Functions like getRealPath in src/store.ts and file scanning operations execute synchronously and will block if the network is slow. Initial indexing of large remote collections may take significantly longer than local equivalents. For best results, use low-latency protocols like NFSv4 or SMB 3.0+ and keep the QMD index directory on local storage.

Can I use relative paths for network-mounted collections?

No, QMD requires absolute paths for all collections. The addCollection function in src/collections.ts stores the path verbatim, and detectCollectionFromPath in src/qmd.ts performs prefix matching that assumes absolute paths. Relative paths may resolve incorrectly if the working directory changes between commands, leading to collection detection failures. Always specify the full absolute path (e.g., /mnt/nfs/docs or Z:\docs).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}