@@ -25,16 +25,10 @@ the container:
2525The rest of the files remain bind-mounted from your host, so edits are visible
2626in the container immediately.
2727
28- ## Requirements
28+ ## Create an ignore file
2929
30- - ToolHive CLI
31- - A mount source directory that contains a ` .thvignore ` file with patterns to
32- exclude
33-
34- ## Create a .thvignore
35-
36- Create a ` .thvignore ` file at the root of the directory you intend to mount. Use
37- simple, gitignore-like patterns:
30+ Create a file named ` .thvignore ` at the root of the directory you intend to
31+ mount. Use simple, gitignore-like patterns:
3832
3933``` text
4034# secrets
@@ -61,60 +55,78 @@ Guidelines:
6155- ` *.ext ` matches any file with that extension directly under the mount source
6256- Lines starting with ` # ` are comments; blank lines are ignored
6357
58+ ::: info [ Pattern matching]
59+
60+ ToolHive uses simple gitignore-like patterns. Advanced gitignore glob syntax
61+ like ` **/*.env ` (to match files in any subdirectory) is not currently supported.
62+ Patterns only match files and directories directly under the mount source.
63+
64+ :::
65+
6466## Run a server with .thvignore
6567
6668Mount your project directory as usual. ToolHive automatically reads ` .thvignore `
6769if present:
6870
6971``` bash
70- thv run --volume ./my-project:/app fetch
72+ thv run --volume ./my-project:/projects filesystem
7173```
7274
7375To print resolved overlay targets for debugging:
7476
7577``` bash
76- thv run --volume ./my-project:/app \
78+ thv run --volume ./my-project:/projects \
7779 --print-resolved-overlays \
78- fetch
80+ filesystem
7981```
8082
8183The resolved overlays are logged to the workload's log file. For a complete list
8284of options, see the [ ` thv run ` command reference] ( ../reference/cli/thv_run.md ) .
8385
8486## Global ignore patterns
8587
86- You can define global ignore patterns at:
87-
88- ``` text
89- ~/.config/toolhive/thvignore
90- ```
88+ You can define global ignore patterns in a platform-specific location:
9189
92- These patterns are loaded in addition to your project's local ` .thvignore ` .
90+ - ** Linux** : ` ~/.config/toolhive/thvignore `
91+ - ** macOS** : ` ~/Library/Application Support/toolhive/thvignore `
92+ - ** Windows** : ` %LOCALAPPDATA%\toolhive\thvignore `
9393
94- - Enabled by default
95- - Disable for a single run:
94+ Patterns contained in the global configuration are loaded in addition to a local
95+ ` .thvignore ` file. To disable global patterns for a specific workload, use the
96+ ` --ignore-globally=false ` option:
9697
9798``` bash
98- thv run --ignore-globally=false --volume ./my-project:/app fetch
99+ thv run --ignore-globally=false --volume ./my-project:/projects filesystem
99100```
100101
101- Recommendation: Store machine-wide patterns (for example, ` .aws/ ` , ` .gcp/ ` ,
102- ` .ssh/ ` , ` *.pem ` , ` .docker/config.json ` ) in the global file, and keep
103- app-specific patterns (for example, ` .env* ` , build artifacts) in your project's
104- local ` .thvignore ` .
102+ ::: tip [ Recommendation]
103+
104+ Set machine-wide patterns (for example, ` .aws/ ` , ` .gcp/ ` , ` .ssh/ ` , ` *.pem ` ,
105+ ` .docker/config.json ` ) in the global file, and keep app-specific patterns (for
106+ example, ` .env* ` , build artifacts) in your project's local ` .thvignore ` .
107+
108+ :::
105109
106110## Troubleshooting
107111
108- - Overlays didn't apply
109- - Ensure ` .thvignore ` exists in the mount source directory (not elsewhere)
110- - Confirm patterns match actual names relative to the mount source
111- - Run with ` --print-resolved-overlays ` and check the workload's log file path
112- displayed by ` thv run `
112+ <details >
113+ <summary >Overlays didn't apply</summary >
114+
115+ - Ensure ` .thvignore ` exists in the mount source directory (not elsewhere)
116+ - Confirm patterns match actual names relative to the mount source
117+ - Run with ` --print-resolved-overlays ` and check the workload's log file path
118+ displayed by ` thv run `
119+
120+ </details >
121+
122+ <details >
123+ <summary >Can't list a parent directory</summary >
124+
125+ - On SELinux systems, listing a parent directory may fail even though specific
126+ files are accessible. Probe individual paths instead (for example, ` stat ` or
127+ ` cat ` ).
113128
114- - Can’t list a parent directory
115- - On SELinux systems, listing a parent directory may fail even though specific
116- files are accessible. Probe individual paths instead (for example, ` stat ` or
117- ` cat ` ).
129+ </details >
118130
119131## Related information
120132
0 commit comments