Skip to content

Commit ac67329

Browse files
committed
Address PR feedback for .thvignore documentation
- Fix global config path to be cross-platform compatible (Linux/macOS/Windows) - Remove redundant Requirements section - Change section heading to 'Create an ignore file' - Update file creation description to be more specific - Replace 'fetch' with 'filesystem' in command examples (better example) - Update troubleshooting section to use collapsible details format - Convert recommendation text to use tip admonition format - Improve global patterns description text - Add clarification about pattern matching limitations (no full glob syntax)
1 parent 2059e08 commit ac67329

File tree

1 file changed

+46
-34
lines changed

1 file changed

+46
-34
lines changed

docs/toolhive/guides-cli/thvignore.md

Lines changed: 46 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -25,16 +25,10 @@ the container:
2525
The rest of the files remain bind-mounted from your host, so edits are visible
2626
in 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

6668
Mount your project directory as usual. ToolHive automatically reads `.thvignore`
6769
if present:
6870

6971
```bash
70-
thv run --volume ./my-project:/app fetch
72+
thv run --volume ./my-project:/projects filesystem
7173
```
7274

7375
To 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

8183
The resolved overlays are logged to the workload's log file. For a complete list
8284
of 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

Comments
 (0)