2015-05-30 13:05:37 +02:00
. \" Man page generated from reStructuredText.
.
2018-09-05 07:45:24 +02:00
.TH "SYNCTHING-STIGNORE" "5" "Sep 02, 2018" "v0.14" "Syncthing"
2015-05-30 13:05:37 +02:00
.SH NAME
syncthing-stignore \- Prevent files from being synchronized to other nodes
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\ $1 \\ n[an-margin]
level \\ n[rst2man-indent-level]
level margin: \\ n[rst2man-indent\\ n[rst2man-indent-level]]
-
\\ n[rst2man-indent0]
\\ n[rst2man-indent1]
\\ n[rst2man-indent2]
. .
.de1 INDENT
. \" .rstReportMargin pre:
. RS \\ $1
. nr rst2man-indent\\n[rst2man-indent-level] \\ n[an-margin]
. nr rst2man-indent-level +1
. \" .rstReportMargin post:
. .
.de UNINDENT
. RE
. \" indent \\n[an-margin]
. \" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
. \" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\ n[rst2man-indent\\n[rst2man-indent-level]]u
. .
.SH SYNOPSIS
.INDENT 0 .0
.INDENT 3 .5
.sp
.nf
.ft C
\& .stignore
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
2016-11-29 11:56:02 +01:00
If some files should not be synchronized to other devices, a file called
2015-05-30 13:05:37 +02:00
\fB \& .stignore\fP can be created containing file patterns to ignore. The
2016-11-29 11:56:02 +01:00
\fB \& .stignore\fP file must be placed in the root of the folder. The
\fB \& .stignore\fP file itself will never be synced to other devices, although it can
\fB #include\fP files that \fI are\fP synchronized between devices. All patterns are
relative to the folder root.
2016-05-04 21:47:08 +02:00
.sp
\fB NOTE:\fP
.INDENT 0 .0
.INDENT 3 .5
Note that ignored files can block removal of an otherwise empty directory.
See below for the (?d) prefix to allow deletion of ignored files.
.UNINDENT
.UNINDENT
2015-05-30 13:05:37 +02:00
.SH PATTERNS
.sp
The \fB \& .stignore\fP file contains a list of file or path patterns. The
\fI first\fP pattern that matches will decide the fate of a given file.
.INDENT 0 .0
.IP \(bu 2
Regular file names match themselves, i.e. the pattern \fB foo\fP matches
the files \fB foo\fP , \fB subdir/foo\fP as well as any directory named
\fB foo\fP \& . Spaces are treated as regular characters.
.IP \(bu 2
Asterisk matches zero or more characters in a filename, but does not
match the directory separator. \fB te*st\fP matches \fB test\fP ,
\fB subdir/telerest\fP but not \fB tele/rest\fP \& .
.IP \(bu 2
Double asterisk matches as above, but also directory separators.
\fB te**st\fP matches \fB test\fP , \fB subdir/telerest\fP and
\fB tele/sub/dir/rest\fP \& .
.IP \(bu 2
Question mark matches a single character that is not the directory
separator. \fB te??st\fP matches \fB tebest\fP but not \fB teb/st\fP or
\fB test\fP \& .
.IP \(bu 2
2016-04-01 09:33:42 +02:00
Characters enclosed in square brackets \fB []\fP are interpreted as a character range \fB [a\- z]\fP \& . Before using this syntax you should have a basic understanding of regular expression character classes.
.IP \(bu 2
2015-05-30 13:05:37 +02:00
A pattern beginning with \fB /\fP matches in the current directory only.
\fB /foo\fP matches \fB foo\fP but not \fB subdir/foo\fP \& .
.IP \(bu 2
A pattern beginning with \fB #include\fP 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
2016-11-29 11:56:02 +01:00
still relative to the folder \fI root\fP \& . Example:
2015-05-30 13:05:37 +02:00
\fB #include more\- patterns.txt\fP \& .
.IP \(bu 2
2016-05-04 21:47:08 +02:00
A pattern beginning with a \fB !\fP prefix negates the pattern: matching files
2015-05-30 13:05:37 +02:00
are \fI included\fP (that is, \fI not\fP ignored). This can be used to override
2018-08-22 07:45:24 +02:00
more general patterns that follow.
2015-05-30 13:05:37 +02:00
.IP \(bu 2
2016-05-04 21:47:08 +02:00
A pattern beginning with a \fB (?i)\fP prefix enables case\- insensitive pattern
2015-05-30 13:05:37 +02:00
matching. \fB (?i)test\fP matches \fB test\fP , \fB TEST\fP and \fB tEsT\fP \& . The
\fB (?i)\fP prefix can be combined with other patterns, for example the
pattern \fB (?i)!picture*.png\fP indicates that \fB Picture1.PNG\fP should
2016-05-04 21:47:08 +02:00
be synchronized. On Mac OS and Windows, patterns are always case\- insensitive.
.IP \(bu 2
A pattern beginning with a \fB (?d)\fP 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.
2015-05-30 13:05:37 +02:00
.IP \(bu 2
A line beginning with \fB //\fP is a comment and has no effect.
2016-04-01 09:33:42 +02:00
.IP \(bu 2
Windows does not support escaping \fB \e[foo \- bar\e] \fP \& .
2015-05-30 13:05:37 +02:00
.UNINDENT
2016-05-04 21:47:08 +02:00
.sp
\fB NOTE:\fP
.INDENT 0 .0
.INDENT 3 .5
2017-11-29 07:45:17 +01:00
Prefixes can be specified in any order (e.g. “(?d)(?i)”), but cannot be in a
single pair of parentheses (not “(?di)”).
2016-05-04 21:47:08 +02:00
.UNINDENT
.UNINDENT
2015-05-30 13:05:37 +02:00
.SH EXAMPLE
.sp
Given a directory layout:
.INDENT 0 .0
.INDENT 3 .5
.sp
.nf
.ft C
2016-06-12 16:17:02 +02:00
\& .DS_Store
2015-05-30 13:05:37 +02:00
foo
foofoo
bar/
baz
quux
quuz
bar2/
baz
frobble
My Pictures/
Img15.PNG
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and an \fB \& .stignore\fP file with the contents:
.INDENT 0 .0
.INDENT 3 .5
.sp
.nf
.ft C
2016-07-26 10:53:00 +02:00
(?d).DS_Store
2015-05-30 13:05:37 +02:00
!frobble
!quuz
foo
*2
qu*
(?i)my pictures
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
2017-11-29 07:45:17 +01:00
all files and directories called “foo”, ending in a “2” or starting with
“qu” will be ignored. The end result becomes:
2015-05-30 13:05:37 +02:00
.INDENT 0 .0
.INDENT 3 .5
.sp
.nf
.ft C
2016-07-26 10:53:00 +02:00
\& .DS_Store # ignored, will be deleted if gets in the way of parent directory removal
2015-05-30 13:05:37 +02:00
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/ # ignored, matched "*2"
baz # ignored, due to parent being ignored
frobble # ignored, due to parent being ignored; "!frobble" doesn\(aq t help
My Pictures/ # ignored, matched case insensitive "(?i)my pictures" pattern
Img15.PNG # ignored, due to parent being ignored
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB NOTE:\fP
.INDENT 0 .0
.INDENT 3 .5
Please note that directory patterns ending with a slash
\fB some/directory/\fP matches the content of the directory, but not the
2015-08-09 11:56:22 +02:00
directory itself. If you want the pattern to match the directory and its
2015-05-30 13:05:37 +02:00
content, make sure it does not have a \fB /\fP at the end of the pattern.
.UNINDENT
.UNINDENT
2017-11-29 07:45:17 +01:00
.SH EFFECTS ON “IN SYNC” STATUS
2015-05-30 13:05:37 +02:00
.sp
Currently the effects on who is in sync with what can be a bit confusing
when using ignore patterns. This should be cleared up in a future
2017-11-29 07:45:17 +01:00
version…
2015-05-30 13:05:37 +02:00
.sp
2016-11-29 11:56:02 +01:00
Assume two devices, Alice and Bob, where Alice has 100 files to share, but
2017-11-29 07:45:17 +01:00
Bob ignores 25 of these. From Alice’ s point of view Bob will become
2015-05-30 13:05:37 +02:00
about 75% in sync (the actual number depends on the sizes of the
2017-11-29 07:45:17 +01:00
individual files) and remain in “Syncing” state even though it is in
fact not syncing anything (\fI \% issue #623\fP <\fB https://github.com/syncthing/syncthing/issues/623\fP >). From Bob’ s point of view, it’ s
2015-11-29 08:55:38 +01:00
100% up to date but will show fewer files in both the local and global
view.
2015-05-30 13:05:37 +02:00
.sp
If Bob adds files that have already been synced to the ignore list, they
2017-11-29 07:45:17 +01:00
will remain in the “global” view but disappear from the “local” view.
2016-11-29 11:56:02 +01:00
The end result is more files in the global folder than in the local,
2017-11-29 07:45:17 +01:00
but still 100% in sync (\fI \% issue #624\fP <\fB https://github.com/syncthing/syncthing/issues/624\fP >). From Alice’ s point of view, Bob
2015-11-29 08:55:38 +01:00
will remain 100% in sync until the next reconnect, because Bob has
already announced that he has the files that are now suddenly ignored.
2015-05-30 13:05:37 +02:00
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2018-02-07 07:45:17 +01:00
2014-2018, The Syncthing Authors
2015-05-30 13:05:37 +02:00
. \" Generated by docutils manpage writer.
.