From 2e6575c660cf2870c990ca04cf04494a37b89351 Mon Sep 17 00:00:00 2001
From: sid <sid@localhost>
Date: Mon, 23 Mar 2026 13:11:43 -0600
Subject: [PATCH] docs: document match_dirs for directory-based host selection

The match_dirs config option was undocumented. Add a dedicated section
explaining directory-based host selection with examples, and update the
hostname resolution priority list to include match_dirs at step 4.
---
 README.md | 35 ++++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9da291f..d0ba488 100644
--- a/README.md
+++ b/README.md
@@ -453,13 +453,45 @@ hosts:
     token: your_token_here
     user: your_username
     git_protocol: ssh
+    match_dirs:
+      - /              # catch-all: use this host when no git remote is detected
   codeberg.org:
     hostname: codeberg.org
     token: another_token
     user: another_username
     git_protocol: https
+    match_dirs:
+      - ~/repos/codeberg   # use this host for repos under this directory
 ```
 
+### Directory-Based Host Selection (`match_dirs`)
+
+When you work with multiple Forgejo/Gitea instances, `fgj` can automatically select the right host based on your current working directory — no `--hostname` flag needed.
+
+Each host entry supports a `match_dirs` list of directory paths. When `fgj` can't determine the host from a git remote, it finds the host whose `match_dirs` entry is the **longest prefix match** for your current directory.
+
+```yaml
+hosts:
+  work.example.com:
+    # ...
+    match_dirs:
+      - ~/work          # any repo under ~/work uses this host
+  personal.example.com:
+    # ...
+    match_dirs:
+      - ~/personal
+      - ~/side-projects  # multiple directories can map to the same host
+  codeberg.org:
+    # ...
+    match_dirs:
+      - /                # catch-all fallback (shortest prefix, lowest priority)
+```
+
+- Paths support `~` expansion and symlink resolution
+- More specific (longer) paths always win over shorter ones
+- Use `/` as a catch-all to override the default `codeberg.org` fallback
+- On ties (same prefix length), the host appearing first in the config file wins
+
 ### Environment Variables
 
 - `FGJ_HOST`: Override the default instance (auto-detected from git remote if not set)
@@ -469,7 +501,8 @@ Hostname is resolved in this priority order:
 1. Command-specific flags (e.g., `--hostname`)
 2. `FGJ_HOST` environment variable
 3. Auto-detected from git remote URL
-4. Default to `codeberg.org`
+4. `match_dirs` lookup (longest prefix match against current directory)
+5. Default to `codeberg.org`
 
 ### Command-line Flags