Fixup #14021 (Manual: document improved path matching for suppressions, file filters, exclusions) (danmar#7680)

Author: danmar

man/manual-premium.md

@@ -102,34 +102,46 @@ need to use both approaches. Later chapters will describe this in more detail.
 
 ### Check files matching a given file filter
 
-With `--file-filter=<str>` you can set a file filter and only those files matching the filter will be checked.
+With `--file-filter=<str>` you can configure file filter(s) and then only those files matching the filter will be checked.
 
-For example: if you want to check only those files and folders starting from a subfolder src/ that start with "test" 
-you have to type:
+For example, this command below means that `src/test1.cpp` and `src/test/file1.cpp` could be checked, but `src/file2.cpp` will not be checked:
 
     cppcheck src/ --file-filter=src/test*
 
-Cppcheck first collects all files in src/ and will apply the filter after that. So the filter must start with the given 
-start folder. 
+You can use `**`, `*` and `?` in the file filter pattern.  
+`**`: matches zero or more characters, including path separators  
+`*`: matches zero or more characters, excluding path separators  
+`?`: matches any single character except path separators
 
-### Excluding a file or folder from checking
+A common use case for `--file-filter` is to check a project, but only check certain files:
 
-To exclude a file or folder, there are two options. The first option is to only provide the paths and files you want to 
-check:
+    cppcheck --project=compile_commands.json --file-filter=src/*.c
 
-    cppcheck src/a src/b
+Typically a `compile_commands.json` contains absolute paths. However no matter if `compile_commands.json` contains absolute paths or relative paths, the option `--file-filter=src/*.c` would mean that:
+ * a file with relative path `test1.c` is not checked.
+ * a file with relative path `src/test2.c` can be checked.
+ * a file with relative path `src/test3.cpp` is not checked.
 
-All files under src/a and src/b are then checked.
+### Excluding a file or folder from checking
 
-The second option is to use -i, which specifies the files/paths to ignore. With this command no files in src/c are 
-checked:
+The option `-i` specifies a pattern to files/folders to exclude. With this command no files in `src/c` are checked:
 
     cppcheck -isrc/c src
 
-This option is only valid when supplying an input directory. To ignore multiple directories supply the -i flag for each 
-directory individually. The following command ignores both the src/b and src/c directories:
+The `-i` option is not used during preprocessing, it can't be used to exclude headers that are included.
+
+You can use `**`, `*` and `?` in the pattern to specify excluded folders/files.  
+`**`: matches zero or more characters, including path separators  
+`*`: matches zero or more characters, excluding path separators  
+`?`: matches any single character except path separators
+
+A use case for `-i` is to check a project, but exclude certain files/folders:
 
-    cppcheck -isrc/b -isrc/c
+    cppcheck --project=compile_commands.json -itest
+
+Typically a `compile_commands.json` contains absolute paths. However no matter if `compile_commands.json` contains absolute paths or relative paths, the option `-itest` would mean that:
+ * a file with relative path `test1.cpp` can be checked.
+ * a file with relative path `test/somefile.cpp` is not checked
 
 ### Clang parser (experimental)
 
@@ -474,19 +486,22 @@ The format for an error suppression is one of:
     [error id]:[filename2]
     [error id]
 
-The `error id` is the id that you want to suppress. The id of a warning is shown in brackets in the normal cppcheck text output. The suppression `error id` may contain \* to match any sequence of tokens.
+The `error id` is the id that you want to suppress. The id of a warning is shown in brackets in the normal cppcheck text output.
+
+The `error id` and `filename` patterns may contain `**`, `*` or `?`.  
+`**`: matches zero or more characters, including path separators  
+`*`: matches zero or more characters, excluding path separators  
+`?`: matches any single character except path separators
 
-The filename may include the wildcard characters \* or ?, which matches any sequence of characters or any single character respectively.
-It is recommended to use forward-slash `/` as path separator on all operating systems. The filename must match the filename in the reported warning exactly.
-For instance, if the warning contains a relative path, then the suppression must match that relative path.
+It is recommended to use forward-slash `/` in the filename pattern as path separator on all operating systems.
 
-## Command line suppression
+### Command line suppression
 
 The `--suppress=` command line option is used to specify suppressions on the command line. Example:
 
     cppcheck --suppress=memleak:src/file1.cpp src/
 
-## Suppressions in a file
+### Suppressions in a file
 
 You can create a suppressions file for example as follows:
 
@@ -517,6 +532,11 @@ You can specify suppressions in a XML file, for example as follows:
       </suppress>
     </suppressions>
 
+The `id` and `fileName` patterns may contain `**`, `*` or `?`.
+`**`: matches zero or more characters, including path separators
+`*`: matches zero or more characters, excluding path separators
+`?`: matches any single character except path separators
+
 The XML format is extensible and may be extended with further attributes in the future.
 
 The usage of the suppressions file is as follows:

man/manual.md

@@ -103,34 +103,46 @@ need to use both approaches. Later chapters will describe this in more detail.
 
 ### Check files matching a given file filter
 
-With `--file-filter=<str>` you can set a file filter and only those files matching the filter will be checked.
+With `--file-filter=<str>` you can configure file filter(s) and then only those files matching the filter will be checked.
 
-For example: if you want to check only those files and folders starting from a subfolder src/ that start with "test" 
-you have to type:
+For example, this command below means that `src/test1.cpp` and `src/test/file1.cpp` could be checked, but `src/file2.cpp` will not be checked:
 
     cppcheck src/ --file-filter=src/test*
 
-Cppcheck first collects all files in src/ and will apply the filter after that. So the filter must start with the given 
-start folder. 
+You can use `**`, `*` and `?` in the file filter pattern.  
+`**`: matches zero or more characters, including path separators  
+`*`: matches zero or more characters, excluding path separators  
+`?`: matches any single character except path separators
 
-### Excluding a file or folder from checking
+A common use case for `--file-filter` is to check a project, but only check certain files:
 
-To exclude a file or folder, there are two options. The first option is to only provide the paths and files you want to 
-check:
+    cppcheck --project=compile_commands.json --file-filter=src/*.c
 
-    cppcheck src/a src/b
+Typically a `compile_commands.json` contains absolute paths. However no matter if `compile_commands.json` contains absolute paths or relative paths, the option `--file-filter=src/*.c` would mean that:
+ * a file with relative path `test1.c` is not checked.
+ * a file with relative path `src/test2.c` can be checked.
+ * a file with relative path `src/test3.cpp` is not checked.
 
-All files under src/a and src/b are then checked.
+### Excluding a file or folder from checking
 
-The second option is to use -i, which specifies the files/paths to ignore. With this command no files in src/c are 
-checked:
+The option `-i` specifies a pattern to files/folders to exclude. With this command no files in `src/c` are checked:
 
     cppcheck -isrc/c src
 
-This option is only valid when supplying an input directory. To ignore multiple directories supply the -i flag for each 
-directory individually. The following command ignores both the src/b and src/c directories:
+The `-i` option is not used during preprocessing, it can't be used to exclude headers that are included.
+
+You can use `**`, `*` and `?` in the pattern to specify excluded folders/files.  
+`**`: matches zero or more characters, including path separators  
+`*`: matches zero or more characters, excluding path separators  
+`?`: matches any single character except path separators
+
+A use case for `-i` is to check a project, but exclude certain files/folders:
 
-    cppcheck -isrc/b -isrc/c
+    cppcheck --project=compile_commands.json -itest
+
+Typically a `compile_commands.json` contains absolute paths. However no matter if `compile_commands.json` contains absolute paths or relative paths, the option `-itest` would mean that:
+ * a file with relative path `test1.cpp` can be checked.
+ * a file with relative path `test/somefile.cpp` is not checked
 
 ### Clang parser (experimental)
 
@@ -475,19 +487,22 @@ The format for an error suppression is one of:
     [error id]:[filename2]
     [error id]
 
-The `error id` is the id that you want to suppress. The id of a warning is shown in brackets in the normal cppcheck text output. The suppression `error id` may contain \* to match any sequence of tokens.
+The `error id` is the id that you want to suppress. The id of a warning is shown in brackets in the normal cppcheck text output.
+
+The `error id` and `filename` patterns may contain `**`, `*` or `?`.  
+`**`: matches zero or more characters, including path separators  
+`*`: matches zero or more characters, excluding path separators  
+`?`: matches any single character except path separators
 
-The filename may include the wildcard characters \* or ?, which matches any sequence of characters or any single character respectively.
-It is recommended to use forward-slash `/` as path separator on all operating systems. The filename must match the filename in the reported warning exactly.
-For instance, if the warning contains a relative path, then the suppression must match that relative path.
+It is recommended to use forward-slash `/` in the filename pattern as path separator on all operating systems.
 
-## Command line suppression
+### Command line suppression
 
 The `--suppress=` command line option is used to specify suppressions on the command line. Example:
 
     cppcheck --suppress=memleak:src/file1.cpp src/
 
-## Suppressions in a file
+### Suppressions in a file
 
 You can create a suppressions file for example as follows:
 
@@ -518,6 +533,11 @@ You can specify suppressions in a XML file, for example as follows:
       </suppress>
     </suppressions>
 
+The `id` and `fileName` patterns may contain `**`, `*` or `?`.
+`**`: matches zero or more characters, including path separators
+`*`: matches zero or more characters, excluding path separators
+`?`: matches any single character except path separators
+
 The XML format is extensible and may be extended with further attributes in the future.
 
 The usage of the suppressions file is as follows: