Skip to content

docs(stignore): add pattern ordering note and common pitfalls section#999

Open
hrubymar10 wants to merge 1 commit intosyncthing:mainfrom
hrubymar10:docs/stignore-pattern-ordering-pitfalls
Open

docs(stignore): add pattern ordering note and common pitfalls section#999
hrubymar10 wants to merge 1 commit intosyncthing:mainfrom
hrubymar10:docs/stignore-pattern-ordering-pitfalls

Conversation

@hrubymar10
Copy link
Copy Markdown

Consider merging this. It took me hours to figure out why my ignore patterns weren't working, and I was only able to understand the issue after analysing the actual source code. It's definitely up to you whether you want to accept this — I just thought it could help some future people who hit the same wall. And yes, both the text in this PR and the documentation changes are AI-generated, but believe me there is a human with intent behind it who verified everything before opening this PR.

Summary

  • Add a note in the Patterns section explaining that !/dir auto-expands to also unignore !/dir/**, and that this affects pattern ordering
  • Add a new "Common Pitfalls" section with a practical .git example showing both incorrect and correct pattern ordering
  • Cross-reference from the note to the new section

Motivation

Users commonly write .stignore patterns in an intuitive but incorrect order — broad whitelist first (!/mydir), then specific exclusions after (/mydir/**/.git/**). This fails silently because Syncthing uses first-match-wins and auto-expands directory unignore patterns. The current documentation doesn't warn about this ordering requirement.

This is especially common when syncing home directories or project folders while trying to exclude .git internals, node_modules, etc.

Changes

  1. Note after first-match-wins explanation — alerts users early that !/dir creates an implicit !/dir/** and links to the pitfalls section
  2. Common Pitfalls section — shows the wrong ordering, explains why it fails, shows the correct ordering, and walks through how each path is matched

Document that !/dir auto-expands to also include !/dir/**, and that
specific ignore patterns must come before the broad !/dir whitelist
to avoid the auto-expansion shadowing them. Add a Common Pitfalls
section with a practical .git example showing both wrong and correct
pattern ordering.
@tomasz1986
Copy link
Copy Markdown
Member

tomasz1986 commented Mar 26, 2026

Just a comment, but ** only actually does anything differently when it's put inside the path, e.g. dir1/**/dir2. Otherwise, you should just use * in any other place.

What I mean is that dir/** and dir/* (and even dir/) all do the same thing, so there is no point in using ** instead of just * in this case.

@calmh
Copy link
Copy Markdown
Member

calmh commented Mar 27, 2026

I think this writeup over-complicates and confuses, honestly, by explaining implementation details like expanded patterns and whatnot. There are two principles that need to be followed & understood:

  1. The first pattern to match wins
  2. Matching a directory matches anything underneath it

Point number two is kind of obvious really, it would be impossible for the ignore pattern foo to make sense and not also match everything under foo/....

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants