syncthing/man/syncthing-stignore.5

222 lines
7.1 KiB
Groff
Raw Normal View History

2015-05-30 11:05:37 +00:00
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-STIGNORE" "5" "Sep 11, 2018" "v0.14" "Syncthing"
2015-05-30 11:05:37 +00: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 10:56:02 +00:00
If some files should not be synchronized to other devices, a file called
2015-05-30 11:05:37 +00:00
\fB\&.stignore\fP can be created containing file patterns to ignore. The
2016-11-29 10:56:02 +00: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 \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
2015-05-30 11:05:37 +00:00
.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
2015-05-30 11:05:37 +00:00
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
2016-11-29 10:56:02 +00:00
still relative to the folder \fIroot\fP\&. Example:
2015-05-30 11:05:37 +00:00
\fB#include more\-patterns.txt\fP\&.
.IP \(bu 2
A pattern beginning with a \fB!\fP prefix negates the pattern: matching files
2015-05-30 11:05:37 +00:00
are \fIincluded\fP (that is, \fInot\fP ignored). This can be used to override
more general patterns that follow.
2015-05-30 11:05:37 +00:00
.IP \(bu 2
A pattern beginning with a \fB(?i)\fP prefix enables case\-insensitive pattern
2015-05-30 11:05:37 +00:00
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.
2015-05-30 11:05:37 +00:00
.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\&.
2015-05-30 11:05:37 +00:00
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
2017-11-29 06:45:17 +00:00
Prefixes can be specified in any order (e.g. “(?d)(?i)”), but cannot be in a
single pair of parentheses (not “(?di)”).
.UNINDENT
.UNINDENT
2015-05-30 11:05:37 +00:00
.SH EXAMPLE
.sp
Given a directory layout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
2016-06-12 14:17:02 +00:00
\&.DS_Store
2015-05-30 11:05:37 +00: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 08:53:00 +00:00
(?d).DS_Store
2015-05-30 11:05:37 +00:00
!frobble
!quuz
foo
*2
qu*
(?i)my pictures
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
2017-11-29 06:45:17 +00: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 11:05:37 +00:00
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
2016-07-26 08:53:00 +00:00
\&.DS_Store # ignored, will be deleted if gets in the way of parent directory removal
2015-05-30 11:05:37 +00: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\(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
2015-08-09 09:56:22 +00:00
directory itself. If you want the pattern to match the directory and its
2015-05-30 11:05:37 +00:00
content, make sure it does not have a \fB/\fP at the end of the pattern.
.UNINDENT
.UNINDENT
2017-11-29 06:45:17 +00:00
.SH EFFECTS ON “IN SYNC” STATUS
2015-05-30 11:05:37 +00: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 06:45:17 +00:00
version…
2015-05-30 11:05:37 +00:00
.sp
2016-11-29 10:56:02 +00:00
Assume two devices, Alice and Bob, where Alice has 100 files to share, but
2017-11-29 06:45:17 +00:00
Bob ignores 25 of these. From Alices point of view Bob will become
2015-05-30 11:05:37 +00:00
about 75% in sync (the actual number depends on the sizes of the
2017-11-29 06:45:17 +00:00
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 Bobs point of view, its
2015-11-29 07:55:38 +00:00
100% up to date but will show fewer files in both the local and global
view.
2015-05-30 11:05:37 +00:00
.sp
If Bob adds files that have already been synced to the ignore list, they
2017-11-29 06:45:17 +00:00
will remain in the “global” view but disappear from the “local” view.
2016-11-29 10:56:02 +00:00
The end result is more files in the global folder than in the local,
2017-11-29 06:45:17 +00:00
but still 100% in sync (\fI\%issue #624\fP <\fBhttps://github.com/syncthing/syncthing/issues/624\fP>). From Alices point of view, Bob
2015-11-29 07:55:38 +00: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 11:05:37 +00:00
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2018-02-07 06:45:17 +00:00
2014-2018, The Syncthing Authors
2015-05-30 11:05:37 +00:00
.\" Generated by docutils manpage writer.
.