Dux Search

Configuration

Configuration

dsearch uses a TOML configuration file to control indexing behavior. The first time you run Dux Search, it creates a default config file at ~/.config/dsearch/config.toml.

Configuration File Location

Default paths:

• Linux/macOS/BSD: ~/.config/dsearch/config.toml

Override with the -c flag:

dsearch -c /path/to/config.toml

Basic Settings

index_path

Where Dux Search stores the index database.

Default:

• Linux/macOS/BSD: ~/.cache/dsearch/index

http_enabled

Whether to serve the HTTP REST API. Off by default. The CLI and DMS talk to the service over a unix socket in $XDG_RUNTIME_DIR, which only your account can reach, so most setups never need HTTP.

The HTTP API has no authentication. Loopback is shared by every account on the machine, so once enabled any local user (or a web page you visit) can search your index, trigger a reindex, or stop the watcher. dsearch serve --http or --listen enables it for one run; dsearch serve --socket forces it off even when the config enables it.

Default: false

http_enabled = true

listen_addr

HTTP server address and port, used when http_enabled is true. Keep it bound to localhost unless you know what you are doing.

Default: 127.0.0.1:43654

listen_addr = "127.0.0.1:43654"

max_file_bytes

Maximum file size to index (in bytes). Larger files are skipped.

Default: 2097152 (2MB)

max_file_bytes = 2097152  # 2MB

worker_count

Number of parallel indexing workers. More workers = faster indexing but higher CPU usage during index operations.

Default: Half your CPU cores (minimum 1)

worker_count = 4

index_all_files

Index all file types, not just text files. When enabled, binary files are indexed by filename only.

Default: true

index_all_files = true

text_extensions

File extensions to extract text content from. Other files are indexed by filename only.

Default:

text_extensions = [
    ".txt", ".md", ".go", ".py", ".js", ".ts",
    ".jsx", ".tsx", ".json", ".yaml", ".yml",
    ".toml", ".html", ".css", ".rs", ".c",
    ".cpp", ".h", ".java", ".rb", ".php", ".sh",
]

Index Paths

Index multiple directories with individual settings using [[index_paths]] blocks. Each path can have its own depth limit and exclusion rules.

Basic Example

[[index_paths]]
path = "/home/brandon"
max_depth = 6
exclude_hidden = true
exclude_dirs = ["node_modules", "venv", "target"]

Configuration Options

path

Directory to index.

max_depth

Maximum directory depth to traverse. Set to 0 for unlimited depth.

Example:

max_depth = 6  # Go 6 levels deep
max_depth = 0  # No limit

exclude_hidden

Skip hidden files and directories (starting with .).

Default: true

exclude_hidden = true

watch

Enable or disable inotify file watchers for this path. When disabled, the path is indexed but changes won't be detected automatically.

Default: true

watch = false  # Disable watchers (useful for network mounts)

extract_exif

Extract EXIF metadata (camera, date taken, GPS, ISO, aperture, focal length) from images under this path.

Default: true

extract_exif = false  # Skip EXIF parsing for code repos

exclude_dirs

List of directory names to skip during indexing. Supports both exact names and regex patterns.

Regex patterns are wrapped in / delimiters (e.g., /^build-/). Each pattern is matched against individual directory name components, not the full path. Invalid regex patterns are skipped with a warning.

By default, exclude_dirs replaces the built-in defaults — anything you list is the complete set of excluded directories for that path. Set merge_default_exclude_dirs to true if you want your list merged onto the defaults instead.

exclude_dirs = [
    "node_modules",     # Exact match
    "/^build-/",        # Regex: excludes build-release, build-debug, etc.
    "/^out-\\d+$/",     # Regex: excludes out-123, out-0, but not "output"
]

Default excludes:

exclude_dirs = [
    # VCS
    ".git", ".hg", ".svn",

    # JavaScript/Node.js
    "node_modules", "bower_components", ".npm", ".yarn",

    # Python
    "site-packages", "__pycache__", ".venv", "venv", ".tox",
    ".pytest_cache", ".eggs",

    # Build outputs
    "dist", "build", "out", "bin", "obj",

    # Rust
    "target",

    # Go
    "vendor",

    # Java/JVM
    ".gradle", ".m2",

    # Ruby
    "bundle",

    # Cache directories
    ".cache", ".parcel-cache", ".next", ".nuxt",

    # OS specific
    "Library", ".Trash-1000",

    # Databases
    ".postgresql", ".mysql", ".mongodb", ".redis",

    # Package manager caches
    "go", ".cargo", ".pyenv", ".rbenv", ".nvm", ".rustup",

    # IDE/Editor
    ".idea", ".vscode",
]

merge_default_exclude_dirs

When true, the path's exclude_dirs list is merged with the built-in defaults (deduplicated) instead of replacing them. Handy when you only want to add a few extras (like a secrets/ directory) without copy-pasting the full defaults array.

Default: false (existing behavior — exclude_dirs replaces the defaults)

[[index_paths]]
path = "~/.dotfiles"
max_depth = 0
exclude_hidden = false        # show dotfiles like .config inside the repo
merge_default_exclude_dirs = true
exclude_dirs = ["secrets"]    # added on top of node_modules, .git, .cache, ...

This is especially useful for indexing dotfiles repos: you want exclude_hidden = false so directories like .config are visible, but you still want noise like .git/ and node_modules/ excluded.

Multiple Index Paths

Configure different indexing strategies for different directories:

# Index home with moderate depth
[[index_paths]]
path = "/home/brandon"
max_depth = 6
exclude_hidden = true
exclude_dirs = ["node_modules", "venv", "target", "dist"]

# Index repos with more depth, exclude VCS
[[index_paths]]
path = "/home/brandon/repos"
max_depth = 8
exclude_hidden = true
exclude_dirs = ["node_modules", "venv", "target", ".git"]

# Index documents fully, including hidden files
[[index_paths]]
path = "/home/brandon/Documents"
max_depth = 0  # No limit
exclude_hidden = false
exclude_dirs = []

# Index network mount without watchers
[[index_paths]]
path = "/mnt/nfs/documents"
max_depth = 5
watch = false  # Disable inotify (not supported on NFS)

Example Configuration

Here's a complete example config:

# Dux Search Configuration
index_path = "/home/brandon/.cache/dsearch/index"
listen_addr = "127.0.0.1:43654"
max_file_bytes = 2097152  # 2MB
worker_count = 4
index_all_files = true

text_extensions = [
    ".txt", ".md", ".go", ".py", ".js", ".ts",
    ".jsx", ".tsx", ".json", ".yaml", ".yml",
    ".toml", ".html", ".css", ".rs", ".c",
    ".cpp", ".h", ".java", ".rb", ".php", ".sh",
]

[[index_paths]]
path = "/home/brandon"
max_depth = 6
exclude_hidden = true
exclude_dirs = [
    "node_modules", "__pycache__", "venv", "target",
    "dist", "build", ".cache"
]

Tips

Speed up indexing: Increase worker_count if you have CPU cores to spare.

Reduce index size: Lower max_file_bytes, add more directories to exclude_dirs, or limit max_depth.

Index everything: Set max_depth = 0 and exclude_dirs = [] for a path you want fully indexed.

Skip binary files: Set index_all_files = false to index only text files.

Troubleshooting

Indexing is slow:

• Check worker_count - try increasing it
• Add common build/cache directories to exclude_dirs
• Reduce max_depth for large directory trees

Search isn't finding files:

• Run dsearch index generate to rebuild the index
• Check if the file's directory is in an index_paths block
• Verify the file isn't in an excluded directory
• Check that exclude_hidden = false if searching for hidden files
• Run dsearch index check <path> to see why a path is excluded

Port already in use:

• Only applies when http_enabled = true; change listen_addr to a different port
• Check what's using the port: netstat -tlnp | grep :43654

Next Steps

• Usage - Learn CLI commands and API usage