123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225 |
- .\" Man page generated from reStructuredText.
- .
- .TH "SYNCTHING-STIGNORE" "5" "Feb 11, 2018" "v0.14" "Syncthing"
- .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
- If some files should not be synchronized to other devices, a file called
- \fB\&.stignore\fP can be created containing file patterns to ignore. The
- \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 \fIare\fP synchronized between devices. All patterns are
- relative to the folder root.
- .sp
- \fBNOTE:\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
- .SH PATTERNS
- .sp
- The \fB\&.stignore\fP file contains a list of file or path patterns. The
- \fIfirst\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 \fBfoo\fP matches
- the files \fBfoo\fP, \fBsubdir/foo\fP as well as any directory named
- \fBfoo\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. \fBte*st\fP matches \fBtest\fP,
- \fBsubdir/telerest\fP but not \fBtele/rest\fP\&.
- .IP \(bu 2
- Double asterisk matches as above, but also directory separators.
- \fBte**st\fP matches \fBtest\fP, \fBsubdir/telerest\fP and
- \fBtele/sub/dir/rest\fP\&.
- .IP \(bu 2
- Question mark matches a single character that is not the directory
- separator. \fBte??st\fP matches \fBtebest\fP but not \fBteb/st\fP or
- \fBtest\fP\&.
- .IP \(bu 2
- 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
- A pattern beginning with \fB/\fP matches in the current directory only.
- \fB/foo\fP matches \fBfoo\fP but not \fBsubdir/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
- still relative to the folder \fIroot\fP\&. Example:
- \fB#include more\-patterns.txt\fP\&.
- .IP \(bu 2
- A pattern beginning with a \fB!\fP prefix negates the pattern: matching files
- are \fIincluded\fP (that is, \fInot\fP ignored). This can be used to override
- more general patterns that follow. Note that files in ignored
- directories can not be re\-included this way. This is due to the fact
- that Syncthing stops scanning when it reaches an ignored directory,
- so doesn’t know what files it might contain.
- .IP \(bu 2
- A pattern beginning with a \fB(?i)\fP prefix enables case\-insensitive pattern
- matching. \fB(?i)test\fP matches \fBtest\fP, \fBTEST\fP and \fBtEsT\fP\&. The
- \fB(?i)\fP prefix can be combined with other patterns, for example the
- pattern \fB(?i)!picture*.png\fP indicates that \fBPicture1.PNG\fP should
- 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.
- .IP \(bu 2
- A line beginning with \fB//\fP is a comment and has no effect.
- .IP \(bu 2
- Windows does not support escaping \fB\e[foo \- bar\e]\fP\&.
- .UNINDENT
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- Prefixes can be specified in any order (e.g. “(?d)(?i)”), but cannot be in a
- single pair of parentheses (not “(?di)”).
- .UNINDENT
- .UNINDENT
- .SH EXAMPLE
- .sp
- Given a directory layout:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .nf
- .ft C
- \&.DS_Store
- 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
- (?d).DS_Store
- !frobble
- !quuz
- foo
- *2
- qu*
- (?i)my pictures
- .ft P
- .fi
- .UNINDENT
- .UNINDENT
- .sp
- all files and directories called “foo”, ending in a “2” or starting with
- “qu” will be ignored. The end result becomes:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .nf
- .ft C
- \&.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/ # ignored, matched "*2"
- baz # ignored, due to parent being ignored
- frobble # ignored, due to parent being ignored; "!frobble" doesn\(aqt 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
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- Please note that directory patterns ending with a slash
- \fBsome/directory/\fP 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 \fB/\fP at the end of the pattern.
- .UNINDENT
- .UNINDENT
- .SH EFFECTS ON “IN SYNC” STATUS
- .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
- version…
- .sp
- Assume two devices, Alice and Bob, where Alice has 100 files to share, but
- Bob ignores 25 of these. From Alice’s point of view Bob will become
- about 75% in sync (the actual number depends on the sizes of the
- individual files) and remain in “Syncing” state even though it is in
- fact not syncing anything (\fI\%issue #623\fP <\fBhttps://github.com/syncthing/syncthing/issues/623\fP>). From Bob’s point of view, it’s
- 100% up to date but will show fewer files in both the local and global
- view.
- .sp
- If Bob adds files that have already been synced to the ignore list, they
- will remain in the “global” view but disappear from the “local” view.
- The end result is more files in the global folder than in the local,
- but still 100% in sync (\fI\%issue #624\fP <\fBhttps://github.com/syncthing/syncthing/issues/624\fP>). From Alice’s point of view, Bob
- will remain 100% in sync until the next reconnect, because Bob has
- already announced that he has the files that are now suddenly ignored.
- .SH AUTHOR
- The Syncthing Authors
- .SH COPYRIGHT
- 2014-2018, The Syncthing Authors
- .\" Generated by docutils manpage writer.
- .
|