aboutsummaryrefslogtreecommitdiff
path: root/Documentation/MANPAGE.md
diff options
context:
space:
mode:
authorEduardo M KALINOWSKI2019-02-16 18:55:54 -0200
committerJakob Unterwurzacher2019-03-26 20:56:37 +0100
commit3bc100aeb3f0763f78c8b3a70165b9f8aaa52db5 (patch)
tree19b1576b0ee8e74612c29b0ff4cec4f3cecf2b29 /Documentation/MANPAGE.md
parent73f9e2374dab47374dc479911a9be5cfebf89378 (diff)
reverse mode: support wildcard exclude (--exclude-wildcard)
This adds support for gitignore-like wildcards and exclude patters in reverse mode. It (somewhat) fixes #273: no regexp support, but the syntax should be powerful enough to satisfy most needs. Also, since adding a lot of --exclude options can be tedious, it adds the --exclude-from option to read patterns from a file (or files).
Diffstat (limited to 'Documentation/MANPAGE.md')
-rw-r--r--Documentation/MANPAGE.md82
1 files changed, 81 insertions, 1 deletions
diff --git a/Documentation/MANPAGE.md b/Documentation/MANPAGE.md
index 5802fb3..6fa5156 100644
--- a/Documentation/MANPAGE.md
+++ b/Documentation/MANPAGE.md
@@ -78,10 +78,29 @@ harvest enough entropy.
#### -e PATH, -exclude PATH
Only for reverse mode: exclude relative plaintext path from the encrypted
-view. Can be passed multiple times. Example:
+view, matching only from root of mounted filesystem. Can be passed multiple
+times. Example:
gocryptfs -reverse -exclude Music -exclude Movies /home/user /mnt/user.encrypted
+See also `-exclude-wildcard`, `-exclude-from` and the [EXCLUDING FILES](#excluding-files) section.
+
+#### -ew PATH, -exclude-wildcard PATH
+Only for reverse mode: exclude paths from the encrypted view, matching anywhere.
+Wildcards supported. Can be passed multiple times. Example:
+
+ gocryptfs -reverse -exclude-wildcard '*~' /home/user /mnt/user.encrypted
+
+See also `-exclude`, `-exclude-from` and the [EXCLUDING FILES](#excluding-files) section.
+
+#### -exclude-from FILE
+Only for reverse mode: reads exclusion patters (using `-exclude-wildcard` syntax)
+from a file. Can be passed multiple times. Example:
+
+ gocryptfs -reverse -exclude-from ~/crypt-exclusions /home/user /mnt/user.encrypted
+
+See also `-exclude`, `-exclude-wildcard` and the [EXCLUDING FILES](#excluding-files) section.
+
#### -exec, -noexec
Enable (`-exec`) or disable (`-noexec`) executables in a gocryptfs mount
(default: `-exec`). If both are specified, `-noexec` takes precedence.
@@ -404,6 +423,67 @@ automated testing as it does not provide any security.
Stop option parsing. Helpful when CIPHERDIR may start with a
dash "-".
+EXCLUDING FILES
+===============
+
+In reverse mode, it is possible to exclude files from the encrypted view, using
+the `-exclude`, `-exclude-wildcard` and `-exclude-from` options.
+
+`-exclude` matches complete paths, so `-exclude file.txt` only excludes a file
+named `file.txt` in the root of the mounted filesystem; files named `file.txt`
+in subdirectories are still visible. (This option is kept for compatibility
+with the behavior up to version 1.6.x)
+
+`-exclude-wildcard` matches files anywhere, so `-exclude-wildcard file.txt`
+excludes files named `file.txt` in any directory. If you want to match complete
+paths, you can prefix the filename with a `/`: `-exclude-wildcard /file.txt`
+excludes only `file.txt` in the root of the mounted filesystem.
+
+If there are many exclusions, you can use `-exclude-from` to read exclusion
+patterns from a file. The syntax is that of `-exclude-wildcard`, so use a
+leading `/` to match complete paths.
+
+The rules for exclusion are that of [gitignore](https://git-scm.com/docs/gitignore#_pattern_format).
+In short:
+
+1. A blank line matches no files, so it can serve as a separator
+ for readability.
+2. A line starting with `#` serves as a comment. Put a backslash (`\`)
+ in front of the first hash for patterns that begin with a hash.
+3. Trailing spaces are ignored unless they are quoted with backslash (`\`).
+4. An optional prefix `!` negates the pattern; any matching file
+ excluded by a previous pattern will become included again. It is not
+ possible to re-include a file if a parent directory of that file is
+ excluded. Put a backslash (`\`) in front of the first `!` for
+ patterns that begin with a literal `!`, for example, `\!important!.txt`.
+5. If the pattern ends with a slash, it is removed for the purpose of the
+ following description, but it would only find a match with a directory.
+ In other words, `foo/` will match a directory foo and paths underneath it,
+ but will not match a regular file or a symbolic link foo.
+6. If the pattern does not contain a slash `/`, it is treated as a shell glob
+ pattern and checked for a match against the pathname relative to the
+ root of the mounted filesystem.
+7. Otherwise, the pattern is treated as a shell glob suitable for
+ consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the
+ pattern will not match a `/` in the pathname. For example,
+ `Documentation/*.html` matches `Documentation/git.html` but not
+ `Documentation/ppc/ppc.html` or `tools/perf/Documentation/perf.html`.
+8. A leading slash matches the beginning of the pathname. For example,
+ `/*.c` matches `cat-file.c` but not `mozilla-sha1/sha1.c`.
+9. Two consecutive asterisks (`**`) in patterns matched against full
+ pathname may have special meaning:
+ i. A leading `**` followed by a slash means match in all directories.
+ For example, `**/foo` matches file or directory `foo` anywhere,
+ the same as pattern `foo`. `**/foo/bar` matches file or directory
+ `bar` anywhere that is directly under directory `foo`.
+ ii. A trailing `/**` matches everything inside. For example, `abc/**`
+ matches all files inside directory `abc`, with infinite depth.
+ iii. A slash followed by two consecutive asterisks then a slash matches
+ zero or more directories. For example, `a/**/b` matches `a/b`,
+ `a/x/b`, `a/x/y/b` and so on.
+ iv. Other consecutive asterisks are considered invalid.
+
+
EXAMPLES
========