Ignoring Files¶
Synopsis¶
.stignore
Description¶
If some files should not be synchronized to (or from) other devices, a file called
.stignore
can be created containing file patterns to ignore. The
.stignore
file must be placed in the root of the synced folder. The
.stignore
file itself will never be synced to other devices, although it can
#include
files that are synchronized between devices. All patterns are
relative to the synced folder root.
The contents of the .stignore
file must be UTF-8 encoded.
Note
Note that ignored files can block removal of an otherwise empty directory. See below for the (?d) prefix to allow deletion of ignored files.
Patterns¶
The .stignore
file contains a list of file or path patterns. The
first pattern that matches will decide the fate of a given file.
Regular file names match themselves, i.e. the pattern
foo
matches the filesfoo
,subdir/foo
as well as any directory namedfoo
. Spaces are treated as regular characters, except for leading and trailing spaces, which are automatically trimmed.Asterisk (
*
) matches zero or more characters in a filename, but does not match the directory separator.te*ne
matchestelephone
,subdir/telephone
but nottele/phone
.Double asterisk (
**
) matches as above, but also directory separators.te**ne
matchestelephone
,subdir/telephone
andtele/sub/dir/phone
.Question mark (
?
) matches a single character that is not the directory separator.te??st
matchestebest
but notteb/st
ortest
.Square brackets (
[]
) denote a character range:[a-z]
matches any lower case character.Curly brackets (
{}
) denote a set of comma separated alternatives:{banana,pineapple}
matches eitherbanana
orpineapple
.Backslash (
\
) “escapes” a special character so that it loses its special meaning. For example,\{banana\}
matches{banana}
exactly and does not denote a set of alternatives as above.
Note
Escaped characters are not supported on Windows, where \
is the
path separator. If you still need to match files that have square or
curly brackets in their names, one possible workaround is to replace
them with ?
, which will then match any character. For example,
you can type ?banana?
to match both [banana]
and
{banana}
, and so on.
A pattern beginning with
/
matches in the root of the synced folder only./foo
matchesfoo
but notsubdir/foo
.A pattern beginning with
#include
results in loading patterns from the named file. It is an error for a file to not exist or be included more than once. Note that while this can be used to include patterns from a file in a subdirectory, the patterns themselves are still relative to the synced folder root. Example:#include more-patterns.txt
.A pattern beginning with a
!
prefix negates the pattern: matching files are included (that is, not ignored). This can be used to override more general patterns that follow.A pattern beginning with a
(?i)
prefix enables case-insensitive pattern matching.(?i)test
matchestest
,TEST
andtEsT
. The(?i)
prefix can be combined with other patterns, for example the pattern(?i)!picture*.png
indicates thatPicture1.PNG
should be synchronized. On Mac OS and Windows, patterns are always case-insensitive.A pattern beginning with a
(?d)
prefix enables removal of these files if they are preventing directory deletion. This prefix should be used by any OS generated files which you are happy to be removed.A line beginning with
//
is a comment and has no effect.
Note
Prefixes can be specified in any order (e.g. “(?d)(?i)”), but cannot be in a single pair of parentheses (not “(?di)”).
Note
Include patterns (that begin with !
) cause Syncthing to traverse
the entire directory tree regardless of other ignore patterns.
If the watcher is enabled, the entire directory
tree will be watched as well.
Top-level include patterns are treated as special cases and will not force Syncthing to
scan (or watch) the entire directory tree. For example: !/foo
is a top-level include
pattern, while !/foo/bar
is not.
Example¶
Given a directory layout starting at the synced folder’s root:
.DS_Store
.stignore
foo
foofoo
bar/
baz
quux
quuz
bar2/
baz
frobble
My Pictures/
Img15.PNG
and an .stignore
file with the contents:
(?d).DS_Store
!frobble
!quuz
foo
*2
qu*
(?i)my pictures
all files and directories called “foo”, ending in a “2” or starting with “qu” will be ignored. The end result becomes:
.DS_Store # ignored, will be deleted if gets in the way of parent directory removal
foo # ignored, matches "foo"
foofoo # synced, does not match "foo" but would match "foo*" or "*foo"
bar/ # synced
baz # synced
quux # ignored, matches "qu*"
quuz # synced, matches "qu*" but is excluded by the preceding "!quuz"
bar2/ # synced, despite matching "*2" due to child frobble
baz # ignored, due to parent being ignored
frobble # synced, due to "!frobble"
My Pictures/ # ignored, matched case insensitive "(?i)my pictures" pattern
Img15.PNG # ignored, due to parent being ignored
Note
Please note that directory patterns ending with a slash
some/directory/
matches the content of the directory, but not the
directory itself. If you want the pattern to match the directory and its
content, make sure it does not have a /
at the end of the pattern.
New in version 1.19.0: Default patterns can be configured which will take effect when automatically
accepting a folder from a remote device. The GUI suggests same the patterns
when adding a folder manually. In either case, the .stignore
file is
created with these defaults if none is present yet.