Problem
Stash currently hardcodes its file filtering logic in listTrackedFiles():
if (entry.name.startsWith(".")) {
continue;
}
This has two issues:
-
No user-configurable ignore rules. There's no way to exclude specific files or directories (e.g. logs/, scratchpad/, node_modules/) from syncing. The only option is to move them out of the stash directory entirely.
-
All dot-files/directories are unconditionally skipped. This is a reasonable default, but it means you can never sync a dot-file even if you want to (e.g. .gitignore, .editorconfig, .claude/). There's no opt-in mechanism.
Proposal
.stashignore
Add support for a .stashignore file at the stash root, using gitignore-style glob patterns:
# Ephemeral / local-only
logs/
scratchpad/
inbox/
read-later/
*.local
*.local.*
# Large / binary
node_modules/
*.mp4
This file itself would be tracked and synced, so ignore rules are consistent across environments.
.gitignore support
If a .gitignore exists in the stash root, respect it as well. .stashignore rules would be additive on top of .gitignore. This is useful when a stash is also a git repo, so you don't have to duplicate ignore rules.
Dot-file handling
Change the default behavior: instead of blanket-skipping all dot-files, only skip .stash/ (stash internals) by default. Let .stashignore handle everything else. Users who want the current behavior can add .* to their .stashignore.
This is a breaking change in the sense that dot-files that were previously invisible will start syncing. A migration path:
- On
stash init, seed .stashignore with .* and !.stashignore to preserve current behavior
- Existing stashes get a warning on first sync after upgrade, suggesting they review their dot-files
Implementation notes
The ignore npm package handles gitignore-style pattern matching and is well-tested. It would slot into listTrackedFiles() as a filter predicate, replacing the startsWith(".") check.
Alternatives considered
- Config in
.stash/config.local.json: Doesn't sync across environments, and JSON arrays of globs are harder to read/edit than a gitignore-style file.
- Only
.gitignore: Not all stashes are git repos, and stash-specific ignores (like *.local) shouldn't pollute .gitignore.
Problem
Stash currently hardcodes its file filtering logic in
listTrackedFiles():This has two issues:
No user-configurable ignore rules. There's no way to exclude specific files or directories (e.g.
logs/,scratchpad/,node_modules/) from syncing. The only option is to move them out of the stash directory entirely.All dot-files/directories are unconditionally skipped. This is a reasonable default, but it means you can never sync a dot-file even if you want to (e.g.
.gitignore,.editorconfig,.claude/). There's no opt-in mechanism.Proposal
.stashignoreAdd support for a
.stashignorefile at the stash root, using gitignore-style glob patterns:This file itself would be tracked and synced, so ignore rules are consistent across environments.
.gitignoresupportIf a
.gitignoreexists in the stash root, respect it as well..stashignorerules would be additive on top of.gitignore. This is useful when a stash is also a git repo, so you don't have to duplicate ignore rules.Dot-file handling
Change the default behavior: instead of blanket-skipping all dot-files, only skip
.stash/(stash internals) by default. Let.stashignorehandle everything else. Users who want the current behavior can add.*to their.stashignore.This is a breaking change in the sense that dot-files that were previously invisible will start syncing. A migration path:
stash init, seed.stashignorewith.*and!.stashignoreto preserve current behaviorImplementation notes
The
ignorenpm package handles gitignore-style pattern matching and is well-tested. It would slot intolistTrackedFiles()as a filter predicate, replacing thestartsWith(".")check.Alternatives considered
.stash/config.local.json: Doesn't sync across environments, and JSON arrays of globs are harder to read/edit than a gitignore-style file..gitignore: Not all stashes are git repos, and stash-specific ignores (like*.local) shouldn't pollute.gitignore.